Not  for  resale 


The  Hitchhiker's 
Guide  to  GEOS 

A  Potpourri  of  Technical  Programming  Notes 

(provided  "as  is"  without  support) 
April  1988 


Copyright  ©1988,.  1989  Berkeley  Softworks. 

This  is  a  copyrighted  work  and  is  not  in  the  public  domain.  However,  you  may  use,  copy,  and 
distribute  this  document  without  fee,  provided  you  do  the  following: 

•  You  display  this  page  prominently  in  all  copies  of  this  work. 

•  You  provide  copies  of  this  work  free  of  charges  or  charge  only  a  distribution  fee  for  the 
physical  act  of  transferring  a  copy. 

Please  distribute  copies  of  this  work  as  widely  as  possible. 

Note:  Berkeley  Softworks  makes  no  representations  about  the  suitability  of  this  work  for  any 
purpose.  It  is  provided  "as  is"  without  warranty  or  support  of  any  kind. 

BERKELEY  SOFTWORKS  DISCLAIMS  ALL  WARRANTIES  WITH  REGARD  TO  THIS 
WORK,  INCLUDING  ALL  IMPLIED  WARRANTIES  OF  MERCHANTABILITY  AND 
FITNESS.  IN  NO  EVENT  SHALL  BERKELEY  SOFTWORKS  BE  LIABLE  FOR  ANY 
SPECIAL,  INDIRECT,  OR  CONSEQUENTIAL  DAMAGES  OR  ANY  DAMAGES 
WHATSOEVER  RESULTING  FROM  LOSS  OF  USE,  DATA,  OR  PROFITS,  WHETHER  IN 
AN  ACTION  OF  CONTRACT.  NEGLIGENCE,  OR  OTHER  TORTIOUS  ACTIONS,  ARISING 
OUT  OF  OR  IN  CONNECnOr^  WITH  THE  USE  OF  THIS  WORK. 


Introduction  (second  edit  /  MGL) 


1/13/88         12:22  PM 


Introduction 


In  1986,  Berkeley  Softworks  pioneerecj  GEOS  —  the  Graphic  Environment  Operating  System  — 
for  the  Commodore  .64.  GEOS  bffered  the  power  of  an  icon/windowing  operating  system,  once 
thought  possible'.on  the  likes  of  Apple's  Macintosh,  to  one  of  the  world's  lowest  priced 
microcomputers.  The  computing  community  quickly  recognized  this  innovation  as  significant:  the 
Software  Publisher's  Association  (SPA)  gave  GEOS  a  Technical  Achievement  Award  and 
Commodore  Business  Machines  endorsed  it  as  the  official  operating  system  for  the  Commodore 
64.  Some  industry  critics  even  said  it  brought  the  Commodore  64  out  of  obsolescence.  Since  that 
time,  GEOS  has  been  ported  to  the  Commodore  128  and,  most  recently,  to  the  Apple  11  family  of 
computers.  Boasting  an  installed  base  approaching  one-million  units,  GEOS  not  only  promises  to 
be  around  for  some  time,  but  to  grow  into^the  operating  system  for  low-end  computers 


Why  Develop  GEOS  Applications 

GEOS  provides  an  environment  for  programmers  and  software  companies  to  quickly  and 
efficiently  develop  sophisticated  applications.  GEOS  insulates  the  programmer  from  the  frustrating 
details  and  dirty  work  usually  associated  with  application  development.  By  using  the  GEOS 
facilities  for  disk  file  handling,  screen  graphics,  menus,  icons,  dialog  boxes,  printer  and  input 
device  support,  the  application  can  concentrate  on  doing  what  it  does  best,  applying  itself  to  the 
task  at  hand,  using  the  GEOS  system  resources,  routines,  and  user-interface  facilities  to  both  speed 
program  development  and  build  better  programs. 

Consistent  User-interface 

A  very  large  portion  of  GEOS  is  devoted  to  supporting  the  user-interface.  THe  GEOS  interface  has 
proven  popular  with  thousands  of  users,  and  an  application  that  takes  advantage  of  this  will  likely 
be  well  received  because  the  users  will  already  be  familiar  with  the  basic  program  operation.  Once 
a  user  has  learned  to  operate  geoWrite,  for  example,  it  is  a  smooth  transition  to  another  application 
such  as  geoCalc. 

Large  Installed  Base  and  Portability 

GEOS  is  currently  available  for  three  machines:  the  Commodore  64,  the  Commodore  128,  and  the 
Apple  11.  There  are  hundreds  of  thousands  of  owners  who  use  GEOS  on  these  machines  and  there 
is  a  correspondingly  large  demand  for  follow-on  products.  With  careful  programming,  an 
application  can  be  developed  to  run  under  all  available  system  configurations  with  only  minor 
changes.  Berkeley  Softworks  plans  to  port  GEOS  to  other  6502-based  microconiputers,  thereby 
further  increasing  the  user  base.  As  the  popularity  of  GEOS  grows,  so  does  the  market  for  your 
product. 

Application  Integration 

GEOS  offers  a  flexible  cut  and  paste  facility  for  text  and  graphic  images.  These  photo  scraps  and 
text  scraps  allow  applications  to  share  data:  a  word  processor  can  use  graphics  from  a  paint 
program  and  a  graph  and  charting  application  can  use  data  from  a  spreadsheet.  The  scrap  format  is 
standard  and  allows  applications  from  different  manufacturers  to  exchange  data,  Berkeley 
Softworks  is  currently  developing  a  second-generation  scrap  facility  for  object-oriented  graphics 
such  as  those  used  in  desktop  publishing  and  CAD  programs. 


1 


Introduction  (second  edit  /  MGL) 


1/13/88 


12:22  PM 


Input  and  Output  Technology 

GEOS  supports  the  concept  of  a  device  driver.  A  device  driver  is  a  small  program  which  co-resides 
with  the  GEOS  Kemal  and  communicates  with  I/O  devices.  Device  drivers  translates  data  and 
parameters  from  a  generalized  format. that  GEOS  understands  into  a  format  relevant  to  the  specific 
device.  GEOS  has  input  drivers  for  mice,  joysticks,  light  pens,  and  other  input  devices,  printer 
drivers  for  text  and  graphic  output  devices  (including  laser  printers),  and  disk  drivers  for  storage 
devices  such  as  floppy  disk  drives,  hard  disks,  and  RAM  expansion  units  (RAMdisks).  As  new 
devices  become  available,  it  is  merely  necessary  to  write  a  driver  to  support  it. 

What  Exactly  is  GEOS? 

First  and  foremost,  GEOS  is  an  operating  system:  a  unified  means  for  an  application  to  interact 
with  peripherals  and  system  resources.  GEOS  is  also  an  environment  —  specifically,  a  graphics- 
based  user-interface  environment  offering  a  standard  library  of  routines  and  visual-based  controls, 
such  as  menus  and  icons.  And  finally,  GEOS  is  a  programmer's  toolbox,  providing  routines  for 
double-precision  integer  math,  random-number  generation,  and  memory  manipulation.. 


NOTE:  GEOS  as  a  general  term  can  represent  full  range  of  concepts  —  an  operating  system,  a 
user  environment,  the  deskTop,  a  group  of  integrated  applications  —  but  in  this  book  it 
usually  refers  specifically  to  the  GEOS  KernaU  the  resident  portion  of  the  operating 

 system  with  which  the  application  deals  with.  


GEOS  As  an  Operating  System 

College  textbook  writers  are  forever  coming  up  with  splendid  new  metaphors  to  describe  operating 
systems.  But  as  the  coach  of  a  baseball  team  or  the  governor  of  California,  an  operating  system  has 
the  same  basic  function:  it  is  the  manager  of  a  computer,  providing  facilities  for  controlling  the 
•  system  while  isolating  the  application  from  the  underlying  hardware.  An  operating  system  allows 
the  application  to  function  in  higher-level  abstract  terms  such  as  "load  a  file  into  memory"  rather 
than  "let  a  bit  rotate  into  the  serial  I/O  shift  register  and  send  an  acknowledge  signal."  The 
operating  system  will  handle  the  laborious  tasks  of  reading  disk  files,  moving  the  mouse  pointer, 
and  printing  to  the  printer, 

GEOS  provides  the  following  basic  operating  system  functions: 

♦  Complete  management  of  system  initialization,  multiple  RAM  banks,  interrupt 
processing,  keyboard/joystick/mouse  input,  as  well  as  an  application  environment  that 
supports  dynamic  overlays  for  programs  larger  than  available  memory,  desk 
accessories,  and  the  ability  to  launch  other  applications. 

•  A  sophisticated  disk  file  system  that  supports  multiple  drives,  fast  disk  I/O,  and  RAM 
disks. 

•  Time-based  processes,  allowing  a  limited  form  of  multitasking  within  an  application. 

♦  Printer  output  support,  offering  a  unified  way  to  deal  with  a  wide  variety  of  printers. 
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GEOS  As  a  Graphic  and  User-Interface  Environment 

Interactive  graphic  interfaces  have  become  the  norm  for  niodem  day  productivity.  GEOS  provides 
a  services  for  placing  lines,  rectangles,  and  images  on  the  screen,  as  well  as  handling  menus, 
icons,  and  dialog  boxes.  Using  the  GEOS  graphic  elements  make  applications  look  better  and 
easier  to  use. 

GEOS  provides  the  following  graphic  and  user-interface  functions: 

•  Multi-level  dynamic  menus  which  can  be  placed  anywhere  on  the  screen.  GEOS 
automatically  handles  the  user's  interaction  with  the  menus  without  permanently 
disrupting  the  display. 

•  Icons  —  graphic  pictures  the  user  can  click  on  to  perform  some  function. 

•  Complete  dialog  box  library  offering  a  standard  set  of  dialog  boxes  (such  as  the  file- 
selector)  ready  for  use.  The  application  may  also  define  its  own  custom  dialog  boxes. 

•  A  library  of  graphic  primitives  for  drawing  points,  lines,  patterned  rectangles,  and 
pasting  photo  scraps  from  programs  like  geoPaint. 

•  Sprite  support.  (Sprites  are  small  graphic  images  which  overlay  the  display  screen  and 
can  be  moved  easily.  The  mouse  pointer,  for  example,  is  a  sprite.) 

•  A  secondary  screen  buffer  for  undo  operations. 
GEOS  As  a  Programmer's  Toolbox 

« GEOS  also  contains  a  large  library  of  general  support  routines  for  math  operations,  string 
manipulations,  and  other  functions.  This  relieves  the  application  programmer  of  the  task  of  writing 
and  debugging  common  routines  ("re-inventing  the  wheel"  as  it  were). 

GEOS  provides  the  following  support  routines: 

•  Double-precision  (two-byte)  math:  shifting,  signed  and  unsigned  multiplication  and 
division,  random  number  generation,  etc. 

•  Copy  and  compare  string  operations. 

•  Memory  functions  for  initializing,  filling,  clearing,  and  moving. 

•  Miscellaneous  routines  for  performing  cyclic  redundancy  checks  (CRC),  initialization, 
error  handling,  and  machine-specific  functions. 

Development  System  Recommendations 

There  are  many  ways  to  develop  GEOS  applications.  Berkeley  Softworks,  for  example,  uses  a 
UNIX™  based  6502  cross  assembler  and  proprietary  in-circuit  emulators  to  design,  test,  and 
debug  GEOS  applications.  Most  developer's,  however,  will  find  this  method  too  costiy  or 
impractical  and  will  opt  to  develop  directly  on  the  target  machines.  Anticipating  this,  Berkeley 
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Softworks  has  developed  geoProgrammer,  an  assembler,  linker,  debugger  package  designed 
specifically  for  building  GEOS  applications. 

geoProgrammer 

geoProgrammer  is  a  sophisticated  set  of  assembly  language  development  tools  designed 
specifically  for  building  GEOS  applications.  geoProgrammer  is  a  scaled-down  version  of  the 
UNIX™  based  development  environment  Berkeley  Softworks  actually  uses  to  develop  GEOS 
programs.  In  fact,  nearly  all  the  functionality  of  our  microPORT™  system  has  been  preserved  in 
the  conversion  to  the  GEOS  environment.  All  sample  source  code,  equates,  and  examples  in  this 
book  are  designed  for  uses  with  geoProgrammer. 

The  geoProgrammer  development  system  consists  of  three  major  components: 

geoAssembler,  the  workhorse  of  the  system,  takes  6502  assembly  language  source  code  and 
creates  linkable  object  files. 

•  Reads  source  text  from  geoWrite  documents;  automatically  converts  graphic  and  icon 
images  into  binary  data. 

•  Recognizes  standard  MOS  Technology  6502  assembly  language  mnemonics  and 
addressing  modes. 

•  Allows  over  1,000  symbol,  label,  and  equate  definitions,  each  up  to  20  characters  long. 

•  Full  16-bit  expression  evaluator  allows  any  combination  of  arithmetic  and  logical 
operations. 

•  Supports  local  labels;,  as  targets  for  branch  instructions. 

•  Extensive  macro  facility  with  nested  invocation  and  multiple  arguments. 

•  Conditional  assembly,  memory  segmentation,  and  space  allocation  directives. 

•  Generates  relocatable  object  files  with  external  definitions,  encouraging  modular 
programming. 

geoLinker  takes  object  files  created  with  geoAssembler  and  links  them  together,  resolving  all 
cross-references  and  generating  a  runable  GEOS  application  file. 

•  Accepts  a  link  command  file  created  with  geoWrite. 

•  Creates  all  GEOS  applications  types  (sequential,  desk  accessory,  and  VLIR),  allowing  a 
customized  header  block  and  file  icon.  geoLinker  will  also  create  standard  Commodore 
applications  which  do  not  require  GEOS  to  run. 

•  Resolves  external  definitions  and  cross-references;  supports  complex  expression 
evaluation  at  link-time. 

•  Allows  over  1,700  unique,  extemally  referenced  symbols. 

•  Supports  VLIR  overlay  modules. 
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geoDebugger  allows  you  to  interactively  track-down  and  eliminate  bugs  and  errors  in  your  GEOS 
applications. 

•  Resides  with  your  application  and  maintains  two  independent  displays:  a  graphics  screen 
for  your  application  and  a  text  screen  for  debugging. 

•  Automatically  takes  advantage  of  a  RAM-expansion  unit,  allowing  you  to  debug 
applications  which  use  all  of  available  program  space. 

•  Complete  set  of  memory  examination  and  modification  commands,  including  memory 
dump,  fill,  move,  compare,  and  find. 

•  Symbolic  assembly  and  disassembly. 

•  Supports  up  to  eight  conditional  breakpoints. 

•  Single-step,  subroutine  step,  loop,  next,  and  execute  commands. 

•  RESTORE  key  stops  program  execution  and  enters  the  debugger  at  any  time. 

•  Contains  a  full-featured  macro  programming  language  to  automate  multiple  keystrokes 
and  customize  the  debugger  command  set. 

Commodore  64 

GEOS  was  first  implemented  on  the  Commodore  64,  and  currentiy  there  are  more  GEOS 
applications  for  this  system  than  the  Apple  II  or  the  Commodore  128.  The  following  is 
recommended  for  developing  under  this  environment: 

•  Commodore  64  or  64c  computer. 

•  Commodore  1351  mouse. 

•  At  least  one  1541  or  1571  disk  drive. 

•  Commodore  1764  or  1751  RAM-expansion  unit. 

•  GEOS  supported  printer. 

•  The  basic  GEOS  operating  system  (GEOS  64),  version  1.3  or  later  which  includes 
geoWrite  and  geoPaint. 

•  geoProgrammer  for  the  Conimodore  64. 
Commodore  128 

The  Commodore  128  may  be  the  ideal  environment  for  prototyping  and  developing  GEOS 
applications  because  it  can  be  used  to  create  programs  which  run  under  GEOS  64  (in  64  emulation 
mode)  and  GEOS  128.  The  128  sports  a  larger  memory  capacity,  and  geoProgrammer  takes 
advantage  of  this  extra  space  for  symbol  and  macro  tables.  The  following  is  recommended  for 
developing  under  this  environment: 
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•  Commodore  128  computer, 

•  Commodore  1351  mouse. 

•  At  least  one  1541  or  1571  disk  drive. 

•  Commodore  1764  or  1751  RAM-expansion  unit. 

•  GEOS  supported  printer. 

•  The  basic  GEOS  operating  system  (GEOS  64),  version  1.3  or  later  which  includes 
geoWrite  and  geoPaint. 

•  The  basic  GEOS  128  operating  system,  version  1.3  or  later  which  includes  geoWrite 
128  and  geoPaint  128. 

•  geoProgrammer  for  the  Commodore  128. 
Apple  II 

The  Apple  II  is  the  latest  addition  to  the  GEOS  family.  The  following  is  recommended  for 
developing  in  this  environment: 

•  Apple  He,  lie,  or  Ilgs  computer. 

•  Apple  Mouse  card. 

•  At  least  one  floppy  disk  drive. 

•  RAM  card  or  hard  disk. 

•  GEOS  supported  printer. 

•  The  basic  GEOS  operating  system  (Apple  GEOS),  which  includes  geoWrite  and 
geoPaint. 

•  geoProgrammer  for  the  Apple  11. 
Other  Useful  GEOS  Applications 

In  addition  to  those  applications  listed  above,  you  may  find  the  following  useful: 

•  GEOS  Icon  Editor  for  customizing  you  icons. 

•  Photo  Manager  and  Text  Manager  for  cutting  and  pasting  text  and  graphics  to  and  from 
your  geoProgrammer  source  code  modules. 

•  Text  Grabber  for  converting  any  6502  source  code  you  may  have  already  written  to 
geoWrite. 
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Graphic  Routines 


As  the  name  GEOS  (Graphics  Environment  Operating  System)  implies,  screen  graphics  are  central 
to  both  the  operating  system  and  its  applications.  GEOS  provides  a  number  of  graphic  primitives 
("primitive"  because  they  are  the  basis  of  more  complex  objects)  for  drawing  points,  lines, 
rectangles,  and  other  objects,  as  well  as  displaying  bitmap  images  such  as  those  cut  from  geoPaint. 
GEOS  also  provides  graphic  support  routines  for  undoing  regions,  inverting  areas,  scrolling,.and 
direcdy  accessing  the  screen  memory. 

Drawing  with  the  built-in  GEOS  routines  increases  program  portability  by  making  much  of  the 
internal,  machine-dependent  screen  architecture  transparent  to  the  application.  When  you  draw  a 
line,  for  example,  you  merely  supply  the  two  endpoints.  GEOS  takes  care  of  calculating  the  proper 
pixel  locations  and  modifying  the  screen  memory.  This  allows  an  application  to  use  the  same  code 
to  draw  lines  on  machines  with  very  different  graphics  hardware  and  spares  the  programmer  from 
dealing  direcdy  with  screen  memory. 

Introduction  to  GEOS  Graphics 

If  you  look  closely  at  a  monitor  or  television  screen,  you  will  notice  that  the  image  is  made  up  of 
many  small  dots.  These  small  dots,  called  pixels,  can  be  either  on  or  off  and  are  represented  in 
memory  by  I's  and  0*s,  respectively.  A  pixel  with  a  value  of  one  is  considered  set  and  a  pixel  of 
value  zero  is  considered  clear.  This  binary,  or  bitwise,  representation  of  images  is  refered  to  as 
bitmapped  graphics,  and  a  bitmap  is  a  picture  or  image  created  in  this  way. 
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Color 

Although  some  hardware  configurations  support  color  graphics,  GEOS  assumes  that  the  screen  is 
a  monochromatic  device;  that  is,  GEOS  only  deals  with  one  drawing  color  and  one  background 
color.  Typically,  the  drawing  color  is  black,  like  ink  and  the  background  color  is  white,  like  a  piece 
of  paper.  Depending  on  the  monitor  being  used  and  the  Preference  Manager  settings,  the  actual 
displayed  colors  may  be  different.  We  will  refer  to  the  color  displayed  by  a  zero-pixel  as  the 
background  color  and  the  color  displayed  with  a  one-pixel  as  the  drawing  color.  Applications  that 
support  multiple  drawing  colors,  such  as  the  Commodore  64  version  of  geoPaint,  must  do  so  on 
their  own,  bypassing  GEOS  (at  the  expense  of  portability)  to  provide  multiple  colors  on  the  screen. 

The  GEOS  Virtual  Screen 

The  GEOS  screen  is  often  referred  to  as  virtual  screen^  one  whose  layout  and  internal  storage 
characteristics  exist  independent  of  any  underlying  graphics  hardware.  For  this  reason,  the  GEOS 
screen  is  fundamentally  identical  under  all  versions  of  the  operating  system. 

The  GEOS  screen  is  a  rectangular  array  of  pixels  arranged  like  a  sheet  of  graph  paper.  Each  pixel 
on  the  screen  has  a  corresponding  (x,y)  coordinate.  The  x-axis  begins  with  zero  and  runs 
horizontally  (left  to  right)  across  the  screen,  and  the  y-axis  begins  with  zero  and  runs  vertically  (top 
to  bottom)  down  the  screen.  The  maximum  x-  and  y-positions,  because  they  differ  from  machine 
to  machine,  are  calculated  by  subtracting  one  from  the  GEOS  constants  SC  FIX  WIDTH  and 
SC  FIX  HEIGHT. 
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Important:    GEOS  does  no  clipping  or  range-checking  on  coordinates  passed  to  it.  If  you  pass 
it  invalid  data  or  coordinates,  Ae  results  are  unpredictable  and  will  often  crash  the 
  application.  
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GEOS  128  40/80-Column  Support 

Because  applications  that  run  under  GEOS  128  may  want  to  take  advantage  of  both  the  40-  and  80- 
column  screen  modes,  the  following  conventions  have  been  adopted  for  the  screen  width  and 
height  constants: 

•  The  following  constants  can  be  used  to  access  the  dimensions  of  the  40-  or  80-column 
screen  specifically: 


SC  40  WIDTH 

Pixel  width  of  40-column  screen. 

SC  40  HEIGHT 

Pixel  height  of  40-column  screen. 

SC  80  WIDTH 

Pixel  width  of  80-column  screen. 

SC  80  HEIGHT 

Pixel  height  of  80-column  screen. 

•  If  the  application  is  designed  to  run  under  GEOS  128  only  and  not  run  under  GEOS  64 
(the  C64  constant  is  set  to  $00  and  the  CI 28  constant  is  set  to  $01 ),  then  the  standard 
SC^PIXJWIDTH  and  SCJPIXJHEIGHT  constants  take  on  the  following  values: 


SC  FIX  WIDTH 

Pixel  width  of  80-column  screen. 

iiC'HX'HElOHT 

Pixel  height  of  80-column  screen. 

•  If  the  application  is  designed  to  run  under  GEOS  64  and  GEOS  128  (both  the  C64 
constant  and  the  C128  constant  set  to  $01),  then  the  standard  SC_PIX_WIDTH  and 
SC_PIX_HEIGHT  constants  take  on  the  following  values: 


WiDtH 

Pixel  width  of  40-column  screen. 

SC  FIX  HElGHt 

Pixel  height  of  40-column  screen. 

This  is  because  the  application  (typically)  will  be  written  with  the  40'Column  screen  in 
mind.  At  runtime,  the  application  can  check  to  see  which  version  of  GEOS  it  is  running 
under  and  add  doubling  bits  to  the  appropriate  coordinate  values  so  that  the  40'Column 
coordinates  will  be  normalized  automatically  when  GEOS  128  is  in  80'Column  mode. 


An  application  can  use  the  following  subroutine  to  determine  whether  it  is  running  under  GEOS 
128  or  GEOS  64: 

.if  (0) 

Checkl28: 

Check  for  GEOS  128. 

Pass : 

nothing 
Returns : 

St         minus  flag  set  if  running  under  GEOS  128, 
Example  usage: 

/ignore  if  under  GEOS  64 

;else,  patch  x-coordinates  with  doubling  bits 

'3 


jsr  Checkl28 

bpl  10$ 

jsr  DoDoubling 

10$: 
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.endif 


Checkl28: 
Ida 
cmp 
bpl 


10$: 


Ida 
rts 


#$12 

version 

10$ 

cl28Flag 


cl28Flag  not  guaranteed  to  be  valid  in  version  1.2  and  lower 
first  see  if  version  <=  1.2 

if  so;  branch  and  say  C64 .  Note  this  is  a  signed  comparison, 
(it  WILL  NOT  work  if  GEOS  goes  beyond  version  $7f !) 
else  set  minus  based  on  high  bit  cl28Flag 


When  running  under  GEOS  128,  the  graphMode  variable  may  be  checked  to  determine  whether 
GEOS  is  in  40- or  80-column  mode: 


bit        graphMode  /  check  40/80  mode  bits 

bpl        C64Mode  ;  branch  if  in  4  0-column  mode 

;  else,  handle  as  80-column... 


For  more  information,  refer  to  "GEOS  128  X-poisition  and  Bitmap  Doubling"  in  this  chapter.  Also 
see  NormalizeX  in  the  Routine  Reference  Section. 


Inclusive  Dimensions 

All  dimensions  and  GEOS  coordinates  are  inclusive:  a  line  contains  the  endpoints  which  define  it, 
and  a  rectangle  includes  the  lines  that  make  up  its  sides.  For  example,  a  rectangle  defined  by  an 
upper-left  comer  of  (10,10)  and  a  lower-right  comer  of  (20,20)  would  include  the  lines  around  its 
perimeter  defined  by  the  points  (10,10),  (10,20),  (20,10),  and  (20,20). 

Linear  Bitmap 

For  the  purpose  of  bitmap  compaction  and  patterns,  the  GEOS  screen  is  treated  as  a  linear  bitmap, 
a  contiguous  block  of  bytes  with  each  bit  controlling  an  individual  pixel.  The  bytes  are  lined  up 
end-to-end  for  each  screen  line!  The  high-order  bit  (bit  7)  of  each  byte  controls  the  leftmost  pixel 
and  the  low-order  bit  (bit  0)  controls  the  rightmost  pixel. 


X-axis 


1 1 1 J 1 1 1 1 1 1 ij  1 1 1  r 


1 

X 

(5* 


byte  0     byte  1 


GEOS  Virtual  Screen 


Keep  in  mind  that  this  is  a  conceptual  organization  of  the  screen;  the  actual  in-memory  storage  of 
the  screen  and  bitmap  data  may  be  very  different 

Dividing  the  Screen  Into  Cards 

Many  GEOS  routines  subdivide  the  GEOS  virtual  screen  into  8x8-pixel  blocks  called  cards.  A  card 
is  a  two-dimensional  unit  of  measurement  eight  pixels  on  each  side.  The  first  card  begins  in  the 
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upper-left  comer  of  the  screen  (0, 0)  and  extends  to  (7, 7).  The  next  card  is  just  to  the  right  of  the 
first  and  extends  from  (8, 0)  to  (15,  7). 

Cards  are  always  aligned  to  eight  pixel  boundaries  called  card  boundaries  (pixel  positions  0,  8, 16, 
24,  etc.).  Aligning  an  object  to  a  card  boundary  is  called  card  alignment^  and  tiie  position  of  an 
object  expressed  in  cards  is  called  its  card  position.  Pixel  position  (32,  72),  for  example,  would 
correspond  to  card  position  (4,  9)  because  32/8  =.4  and  72/8  =  9).  The  card  width  of  an  object  is 
its  width  in  cards,  and  the  card  height  is  its  height  in  cards.  An  entire  row  of  cards  is  called  a 
cardrow. 


The  card  is  a  convenient  unit  of  measurement  because  its  dimensions,  8x8,  which  is  a  power  of  2, 
lend  themselves  to  simple  binary  arithmetic.  For  example,  converting  a  pixel  position  to  a  card 
position  is  merely  a  matter  shifting  right  three  times. 

Example: 


MseToCardPos : 

converts  current  mouse  positions  to  card  position 


Pass : 
Uses : 
Returns : 

Destroys : 


nothing 

MouseXPos,  MouseYPos 

rOL  mouse  card  x-position  (byte) 
rOH        mouse  card  y-position  (byte) 


a,x,y 

(mgl) 

llr  It  1^       **************************  * 

MseToCardPos: 


php 

•  save  current  interrupt  disable  status 

sei 

•  disable  interrupts  so  mouseXPos  doesn't  change 

MoveW 

MouseXPos,  rO 

'  copy  mouse  x-position  to  zp  work  reg  (ro) 

pip 

•  reset  interrupt  status  asap. 

Idx 

#rO 

•  divide  x-position  (rO)  by  8 

Idy 

#3 

•   (shift  right  3  times) 

jsr 

DShiftRight 

•  this  gives  us  the  card  x-position  in  rOL 

Ida 

MouseYPos  , 

•  get  mouse  y-position 

Isr 

a  t 

'  and  shift  right  3  times 

Isr 

a  < 

•  which  is  a  divide  by  8 

Isr 

a  t 

•  and  gives  us  the  card  y-position  in  a 

sta 

rOH 

•  set  down  card  y-position 

rts 

•  exit 

Cards  are  also  convenient  because  they  map  directly  to  the  internal  storage  format  of  the 
Commodore  40-column  graphics  screen.  (Converting  to  other  formats,  such  as  the  Commodore 
128  80-column  screen  or  the  Apple  n  double  hi-res  screen,  requires  additional  translation.  This 
translation  is  handled  automaticdly  by  the  GEOS  graphics  routines.) 


Display  Buffering 


Normally  the  application  has  control  of  the  screen.  But  when  an  item  such  as  a  dialog  box  or  a 
menu  is  displayed,  GEOS  overwrites  the  screen.  When  the  dialog  box  is  removed  or  the  menu  is 
retracted,  GEOS  needs  to  restore  the  portion  of  the  screen  it  destroyed.  For  this  purpose,  GEOS 
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maintains  a  background  screen  buffer.  Most  of  the  time,  the  background  buffer  contains  an  exact 
copy  of  the  foreground  screen  (rfie  screen  that  is  displayed)  because  GEOS  normally  sends 
graphics  data  to  both  screen  buffers.  When  a  temporary  object  is  displayed,  however,  it  is  only 
drawn  to  the  foreground  screen.  Removing  the  object,  or  recovering  the  original  area  of  the  screen, 
is  then  simply  a  matter  of  copying  pixels  from  the  background  buffer  to  the  foreground  screen.  The 
GEOS  dialog  box  and  menu  routines- handle  this  sort  of  recovery  automatically. 

dispBufferOn 

Usually  the  application  will  want  to  draw  to  both  buffers  so  that  GEOS  can  properly  recover  the 
foreground  screen  after  menus  and  dialog  boxes.  If  graphics  are  only  drawn  to  one  buffer  and  a 
menu  is  brought  down  or  a  dialog  box  is  displayed,  the  subsequent  recover  may  restore  the  wrong 
data. 

However,  sometimes  an  application  may  want  to  limit  drawing  to  only  the  foreground  or 
background  screen  buffer.  GEOS  graphics  and  text  routines  use  the  global  variable 
dispBufTerOn  to  determine  whether  to  draw  to  the  foreground  screen,  the  background  buffer,  or 
both  simultaneously.  Bits  6  and  7  of  dispBufferOn  determine  the  writing  and  reading  mode: 


bit  7: 

i 

1      —  use  foreground  screen. 

0     —  do  not  use  foreground  screen. 

bit  6: 

1      —  use  background  buffer. 

0     —  do  not  use  background  buffer. 

bits  5-0: 

reserved  for  future  use  —  should  always  be  0. 

There  are  some  constants  which  allow  you  to  gain  access  to  these  bits: 

ST^WR^FORE      use  foreground. 
ST_WR_B  ACK     use  background. 

and  they  can  be  used  in  following  manner: 

;Use  both  foreground  screen  and  background  buffer  (normal) . 
LoadB  dispBufferOn,   #  (ST__WR_FORE  I  ST_WR_BACK) 

;Use  foreground  screen  only. 

LoadB  dispBufferOn,  #ST__WR_FORE 

;Use  background  buffer  only. 

LoadB  dispBufferOn,  #ST_WR_BACK 

Note:  If  bits  6  and  7  of  dispBufferOn  are  both  zero,  GEOS  considers  this  an  undefined 
state  and  will  not  produce  useful  results.  In  most  cases,  the  internal  address  calculations 
will  force  your  graphic  objects  to  appear  in  the  center  of  the  drawing  area  where  they 
can  do  little  harm.  If  the  center  line  on  the  screen  becomes  garbled,  dispBufferOn 

 probably  contains  a  bad  value. 

Using  dispBufferOn 

Typically  applications  leave  dispBufferOn  set  to  draw  to  both  screens,  whereas  most  desk 
accessories  will  only  draw  to  the  foreground  screen.  In  some  situations,  an  application  may  want 
to  limit  drawing  to  the  foreground  screen  so  that  it  may  recover  from  the  background  buffer  at  a 
later  time.  Internally  this  is  what  GEOS  does  when  it  opens  a  menu  or  dialog  box:  the  object  is 
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only  drawn  to  the  foreground  screen,  and  when  it  needs  to  be  erased,  the  original  data  is  recovered 
from  the  background  buffer.  dispBufTerOn  can  also  be  used  to  pre-draw  complex  objects  in  the 
background  buffer  (ST_WR_BACK)  and  make  them  instantly  appear  on  the  foreground  screen 
by  doing  a  recover.  " 

An  application  must  take  special  precautions.when  using  dispBufferOn  to  draw  selectively  to 
one  buffer  or  the  other.  For  example,  when  GEOS  automatically  recovers  from  a  menu  or  a  dialog 
box,  it  recovers  the  data  from  the  background  buffer.  If  the  background  buffer  has  not  been 
updated  (the  application  has  been  drawing  with  the  ST_WR_BACK  bit  cleared,  for  example), 
then  the  menu  or  dialog  may  recover  the  wrong  data. 

Since  dialog  boxes  are  only  displayed  when  the  the  application  calls  DoDlgBox  and  menus  are 
only  opened  while  GEOS  is  in  MainLoop,  the  application  has  some  control  over  GEOS's 
automatic  recovering.  The  application  can  postpone  displaying  dialog  boxes  and  returning  to 
MainLoop  until  the  foreground  screen  and  background  buffer  contain  the  same  data.  If  an 
application  must  return  to  MainLoop  while  the  buffers  contain  different  data  (to  let  processes  run, 
for  example),  it  can  always  disable  menus  by  clearing  the.MENUON_BIT  bit  of  mouseOn.  The 
menus  may  be  reenabled  again  by  restoring  the  MENUON_BIT  bit  of  mouseON: 

Example: 


StopMenus : 

MoveB 

rmbf 

rts 


mouseOn, oldMouseOn 
MENUON  BIT,mouseOn 


save  current  enable  status  for  later 

disable  menus  temporarily 

exit. 


RestartMenus : 
Ida 
and 
ora 
sta 
rts 


OldMouseOn : 


OldMouseOn 

#(%1  «MENUON_BIT) 

mouseOn 

mouseOn 


.byte  $00 


get  old  menu  enable  status 
ignore  all  but  menu  bit 
restore  old  menu  bit 
in  current  mouseOn  byte 
exit 

temp  save  area  for  mouseOn  variable 


Using  the  Background  Buffer  as  Extra  Memory 

Some  applications  are  so  starved  for  memory  that  they  opt  to  use  the  background  buffer  for 
program  code  or  data.  To  do  this,  they  must  always  keep  the  ST_WR  BACK  bit  of 
dispBufferOn  clear  so  that  the  background  buffer  is  not  corrupted  with  graphic  3ata. 

If  you  disable  the  background  buffer,  GEOS  cannot  automatically  recover  after  menus  and  dialog 
boxes.  The  application  must  provide  its  own  routine  for  restoring  the  foreground  screen.  There  is  a 
GEOS  vector  called  RecoverVector,  which  normally  points  to  the  RecoverRectangle 
routine.  Whenever  GEOS  needs  to  recover  from  a  menu,  dialog  box,  or  desk  accessory,  it  sets  up 
parameters  as  if  it  were  going  to  call  RecoverRectangle  and  jsr's  indirectly  through  the  address 
in  RecoverVector.  If  the  application  is  using  the  background  buffer,  it  must  place  the  address  of 
its  own  screen  recover  routine  in  RecoverVector.  When  GEOS  needs  to  recover  a  portion  of  the 
screen,  it  will  jsr  to  the  application's  recover  routine  with  the  following  register  values  describing 
the  rectangular  area  to  recover: 

r3  XI  —  x-coordinate  of  upper-left  (word). 

r2L  Yl  —  y-coordinate  of  upper-left  (byte). 

r4  X2  —  x-coordinate  of  lower-right  (word). 

r2H  Y2  —  y-coordinate  of  lower-right  (byte). 
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where  (X1,Y1)  is  the  upper-left  comer  and  (X2,Y2)  is  the  lower-right  comer  of  the  rectangular 
area  to  recover.  The  rectangle's  coordinates  are  inclusive.  The  application  must  then  use  these 
values  to  restore  the  portion  of  the  screen  that  lies  within  the  rectangle's  boundaries  and  retum  with 
an  rts.  This  recovery  can  be  as  simple  as  filling  with  a  halftoned  pattern  or  as  involved  as 
redrawing  graphic  and  text  objects  that  fall  within  the  rectangular  recover  area. 

Most  of  the  larger  Berkeley  Softworks  GEOS  applications  use  a  technique  called 
saveFG/recoverFG  (short  for  "save  foreground"  and  "recover  background")  to  save  and  recover 
the  foreground  screen  when  displaying  menus  and  dialog  boxes.  Basically,  saveFG  will  save  a 
rectangular  subregion  of  the  foreground  screen  to  a  special  buffer  just  before  GEOS  displays  a 
menu  or  a  dialog  box.  When  GEOS  tries  to  recover  from  the  background  buffer,  recoverFG 
restores  the  data  from  the  special  buffer.  Although  the  size  of  the  buffer  varies  from  application  to 
application,  it  will  seldom  be  larger  than  5.5K  (just  large  enough  to  hold  the  largest  standard 
dialog  box). 

Transferring  data  to  and  from  the  buffer  is  fairly  straightforward.  With  the  Commdore  40-column 
screen,  it  is  mostly  a  matter  of  calculating  the  proper  address  offsets  and  copying  bytes.  With  the 
GEOS  128  80-column  screen,  the  process  is  compUcated  a  bit  because  the  bytes  must  be  read  from 
the  VDC  chip's  RAM.  With  Apple  GEOS,  the  process  is  simplicity  itself  because  there  are  two 
routines  for  saving  and  restoring  automatically:  saveFG  and  recoverFG. 

The  real  trick  is  knowing  how  to  intercept  the  normal  GEOS  menu  and  dialog  box  drawing  and 
recovering  mechanisms.  Dialog  boxes  are  the  easiest  because  they  are  always  called  by  the 
application.  The  program  only  needs  to  save  the  foreground  screen  area  prior  to  calling 
DoDIgBox.  The  size  of  the  dialog  box  can  be  caculated  from  its  table  (be  sure  to  account  for  any 
shadow)  and  the  foreground  data  can  be  copied  into  the  saveFG  buffer.  When  the  dialog  box  is 
finished,  GEOS  will  jsr  through  RecoverVector.  The  application  installs  its  own  recoverFG 
routine  into  RecoverVector  and  restores  the  foreground  area  from  the  saveFG  buffer.  The 
GEOS  dialog  box  recovery  does  have  one  quirk  that  concerns  shadowed  dialog  boxes.  GEOS 
shadowed  dialog  boxes  consists  of  two  overlapping  rectangular  areas:  the  actual  diaJog  box  and  the 
slightly  offset  shadow  rectangle.  GEOS  first  calls  through  RecoverVector  once  for  the  region 
bounded  by  the  shadow  box,  then  again  for  the  region  bounded  by  the  dialog  box.  When  saving 
the  foreground  area,  the  entire  dialog  box  region  (the  area  bounded  by  the  union  of  all  eight  comer 
points)  should  be  saved  and  a  special  flag  should  be  set  so  that  the  area  is  only  recovered  once. 
Under  Apple  GEOS,  the  recovery  of  dialog  box  shadows  can  be  suppressed  by  setting 
recoverOnce  to  a  non-zero  value.  When  recoverOnce  is  non-zero,  GEOS  only  vectors  through 
RecoverVector  once  with  the  bounding  rectangle  of  the  dialog  box.  The  application's  recover 
routine  will  need  to  compensate  for  the  shadow  box.  For  more  information  on  dialog  boxes,  refer 
to  Chapter  @DLG@ . 

Saving  the  foreground  area  before  a  menu  is  displayed  is  a  bit  tougher  because  GEOS  displays 
menus  at  MainLoop,  the  application  has  little  notice  that  a  submenu  is  opening  up.  Fortunately, 
there  is  a  workaround:  GEOS  supports  a  special  type  of  sub-menu  called  a  dynamic  sub-menu. 
Just  before  a  dynamic  sub-menu  opens,  GEOS  calls  a  subroutine  whose  address  is  stored  in  the 
menu  data  structure.  This  opporunity  can  be  used  to  save  the  foreground  screen  area  before  GEOS 
draws  the  menu  by  calculating  the  bounding  rectangle  from  the  menu  structure.  When  GEOS 
recovers  a  menu,  it  calls  through  RecoverVector  as  it  does  with  dialog  boxes.  With  multiple 
sub-menus,  the  menus  are  always  recovered  in  the  reverse  order  they  were  drawn.  For  more 
information  on  menus,  refer  to  Chapter  @ICNMENU@ 
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Manual  Imprinting  and  Recovering 

Within  an  application,  data  can  be  moved  between  the  foreground  screen  and  background  buffer 
with  GEOS  routines  that  copy  data  to  and  from  the  two  areas.  Copying  data  from  the  foreground 
screen  to  the  background  buffer  is  called  imprinting,  and  copying  data  from  the  background  buffer 
to  the  foreground  screen  is  called  recovering.  There  are  GEOS  routines  for  imprinting  and 
recovering  points,  lines,  and  rectangular  regions. 

Some  Possible  dispBufferOn  Complications 

When  drawing  with  both  buffers  enabled  (with  both  foreground  and  background  bits  set  in 
dispBufferOn),  GEOS  requires  that  the  foreground  screen  and  the  background  buffer  contain 
exacdy  the  same  data.  If  they  are  different,  the  resuhs  of  graphic  operations  may  be  unpredictable. 
If  you  need  to  draw  to  the  foreground  screen  and  the  background  buffer  when  they  contain 
different  data,  you  must  perform  the  graphic  operation  once  by  writing  only  to  the  foreground 
screen,  and  then  a  second  time,  writing  only  to  the  background  buffer  —  you  cannot  write  to  both 
of  screen  areas  simultaneously  if  they  contain  different  data. 

Machine  Dependencies 

The  GEOS  graphics  routines  hide  much  of  the  underlying  hardware  from  the  application.  This 
allows  the  same  code  to  run  under  a  variety  of  different  environments  with  very  few  changes. 
However,  it  is  sometimes  necessary  to  optimize  graphic  routines  for  a  specific  machine.  This  can 
be  as  simple  as  taking  advantage  of  color  display  capabilities  or  as  complex  as  direct  screen 
memory  manipulation.  Either  way,  an  application  should  only  resort  to  such  tactics  when  the 
desired  effect  cannot  be  achieved  through  the  standard  graphics  routines.  Be  aware  that 
circumventing  the  GEOS  Kemal  will  very  likely  increase  your  development  time  and  that  there  is 
no  guarantee  that  the  techniques  will  be  compatible  with  future  versions  of  GEOS. 

Commodore  64 

The  Commore  64  version  of  GEOS  uses  the  standard  high-resolution  bitmap  mode  (not  multi-color 
bitmap  mode),  which  is  320  pixels  wide  by  200  pixels  high.  Memory  is  mapped  to  the  screen  in 
eight-byte  stacks  called  cards:  byte  0  controls  pixels  (0,0)  through  (7,0),  with  bit  7  on  the  left  and 
bit  0  on  the  right,  and  byte  1  controls  the  same  pixels  on  the  Une  below,  which  is  pixels  (0,1) 
through  (7,1).  This  stacking  continues  through  byte  7,  which  controls  pixels  (0,7)  through  (7,7) 
and  completes  the  8x8-pixel  card.  Byte  8  begins  the  next  card,  controlling  pixels  (8,0)  through 
(15,0).  The  screen  memory  begins  at  SCREEN  BASE  and  occupies  8,000  bytes,  extending  to 
SCREEN_BASE+7999.  The  background  buf^r  begijis  at  BACK  SCR  BASE  and  extends 
to  BACK^SCR_BASE+7999. 

GEOS  does  not  directly  support  the  foreground  and  background  color  options  of  the  standard 
high-resolution  bitmap  mode.  The  color  matrix,  located  from  COLOR_MATRIX  to 
COLOR  MATRIX+999,  is  set  to  a  constant  foreground  and  background  color  as  determined 
by  the  Preference  Manager.  If  an  application  wants  to  support  color  Gike  geoPaint),  it  must  manage 
the  color  matrix  itself.  Each  byte  in  the  color  matrix  sets  the  foreground  and  background  colors  of  a 
card  (8x8  pixel  block):  color  byte  0  sets  the  colors  for  card  0  (bitmap  bytes  0-7)  and  color  byte  1 
sets  the  colors  for  card  1  (bitmap  bytes  8-15).  Before  the  application  exits,  it  must  restore  the 
original  color  matrix.  This  best  done  by  sa;ving  the  first  byte  and  then  filling  the  color  matrix  before 
calling  EnterDeskTop,  as  the  following  code  fragments  illustrate: 


Example: 
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;0n  entry,  save  off  the  first  byte  of  the  color  matrix 
MoveB     COLOR_MATRIX, saveColor 


;0n  exit,  fill  the  color  matrix  with  the  saved  value 

LoadW     rO,#1000  /color  matrix  is  1000  bytes 

LoadW     r 1 , #COLOR_MATRIX 

MoveB     saveColor, r2L   ;fill  with  original  color 
jsr  FillRam 

Commodore  128 

In  40-column  mode,  GEOS  128  screen  memory  is  identical  to  the  Commodore  64.  In  80-column 
mode,  GEOS  128  uses  the  high-resolution  640x200  mode  supported  by  the  8563  VDC  (Video 
Display  Controller)  chip..  The  foreground  screen  memory  is  not  stored  in  the  normal  Commodore 
memory  but  on  the  VDC  chip  instead.  The  VDC  RAM  is  accessed  indirecdy  through  the  VDC 
control  registers.  The  screen  occupies  16,000  bytes,  and  each  byte  is  accessed  one  at  time  by  its 
address  within  the  VDC  display  RAM(the  first  screen  byte  is  at  0,  the  last  at  15999).  Bits  are 
mapped  sequentially  from  memory  to  the  screen  pixels:  bits  7  through  0  of  byte  0  (in  that  order) 
control  the  first  seven  pixels,  (0,0)  through  (7,0).  The  following  byte  controls  the  next  seven 
pixels,  (8,0)  through  (15,0).  And  so  on  for  the  remainder  of  the  screen.  The  following  two 
subroutines  will  access  bytes  in  the  VDC  screen  RAM  when  GEOS  128  is  in  80-column  mode: 

Example: 


***********************************  **«***«***«****«4r**********«**«***-****««^ 


StaSOFore 
LdaSOFore 


Pass : 


r5 
A 


—  stores  byte  to  128  80-column  foreground  screen 

—  loads  byte  from  128  80-column  foreground  screen 


=  address  in  foreground  memory 
=  data  value  (for  StaSOFore) 


Returns: 
A 

Destroyed: 
x 


»  data  value  (for  Lda80Fore) 


Note:   Call  TempHideMouse  to  disable  software  sprites  before  accessing 
foreground  screen  directly. 

(mgl) 

Constants  for  VDC  internal  registers 


VDC_HI_UPDATE 
VDC_LO_UPDATE 
VDC  DATA 


18 
19 
31 


/update  hi-byte  of  VDC  pointer 
/update  lo-byte  of  VDC  pointer 
;data  byte  at  current  VDC  pointer 


StaSOFore: 

;  Send  data  byte  to  the  VDC  chip 

jsr  NewVDCAddress 

Idx  #VDC_DATA 

stx  VDC 

30$:       bit  VDC 

bpl  30$ 

sta  VDC+1 

rts 


Update  VDC  address  with  fg  screen  pointer  (r5) 
request  VDC  data  register 

test  VDC  status 

loop  till  VDC  ready  for  data  byte 

store  data  byte 

exit 
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LdaSOFore: 

;  Get  data  byte  from  the  VDC  chip 

jsr        NewVDCAddress  ;  Update  VDC  address  with  fg  screen  pointer  (r5) 

Idx        #VDC__DATA  ;  request  VDC  data  register 
stx  VDC 

30$:       bit        VDC  ;  t^st  VDC  status 

bpl        30$  ;  loop  till  data  byte  ready 

Ida        VDC+1  ;  get  data  byte 

rts  /  exit 

NewVDCAddress : 


;  Transfer  value  in  r5  to  VDC  internal  hi/lo  address  register. 


;  Destroys: 

X 

Idx 

#VDC_HI__UPDATE 

ask  VDC  for  high  byte 

stx 

VDC 

10$: 

bit 

VDC 

•  check  VDC  status 

bpl 

10$ 

•  and  loop  till  VDC  ready 

Idx 

r5H 

•  store  hi-byte  of  address 

stx 

VDC+1 

•  to  VDC  chip 

Idx 

#VDC_LO_UPDATE 

•  ask  VDC  for  low-byte 

stx 

VDC 

20$: 

bit 

VDC 

•  check  VDC  status 

bpl 

20$ 

•  and  loop  till  VDC  ready 

Idx 

r5L 

•  store  lo-byte  of  address 

stx 

VDC+1 

•  to  VDC  chip 

rts 

•  exit 

For  more  information  on  controlling  the  8563  VDC  chip,  refer  to  the  Commodore  128 
Programmer's  Reference  Guide. 

Before  writing  directly  to  the  80-column  foreground  screen,  be  sure  to  call  TempHideMouse  to 
temporarily  disable  the  virtual  sprites  (for  more  information,  refer  to  TempHideMouse  in 
Chapter  XX). 

c 

Because  the  80-column  screen  requires  a  16,000-byte  background  buffer,  GEOS  128  (when  in  80- 
column  mode)  uses  the  8,000-byte  40-column  screen  foreground  buffer  (SCREEN  BASE  to 
SCREEN_BASE+7999)  for  store  the  first  100  scanlines  of  background  buffer  data  and  the 
8,000-byte  foreground  screen  buffer  (BACK_^SCR_BASE  to  BACK_SCR_BASE+7999) 
to  store  the  last  100  scanlines  of  background^buffeF  data.  Because  these  data  areas  are  not 
contiguous,  an  application  that  directly  accesses  the  background  screen  must  compensate  for  this 
break. 


Apple  II 

Apple  GEOS  uses  the  double  hi-res  screen,  which  is  560  pixels  wide  by  192  pixels  high.  The 
seven  lower  bits  (0-6)  of  each  graphic  byte  are  displayed  in  bit  0  to  bit  6  order  on  the  screen,  and 
bit  7  is  ignored  (not  displayed).  That  is.  Pixel  (0,0)  is  controlled  by  bit  0  of  byte  0,  pixel  (1,0)  is 
controlled  by  bit  1  of  byte  0,  and  pixel  (7,0)  is  controlled  by  bit  0  of  byte  1.  The  graphic  screen  is 
located  in  memory  at  SCREEN^BASE  ($2000)  to  SCREEN_BASE+$lfff  ($3fff)  in  both  the 
main  and  auxiliary  memory  banks?  The  bytes  in  main  memory  are  mapped  to  odd  byte  positions  on 
the  screen  (bytes  1,3,5...),  and  the  bytes  in  auxiliary  memory  are  mapped  to  even  byte  positions 
on  the  screen  (byte  0,2,4...).  This  means  that  adjacent  bytes  on  the  screen  are  in  separate  banks  of 
memory.  For  example,  byte  0  is  located  at  $2000  in  the  auxiliary  bank  and  byte  1  is  located  at 
$20(X)  in  the  main  memory  bank.  (For  more  information  on  accessing  the  Apple  foreground  screen 
across  memory  banks,  refer  to  GetScanLine  in  the  Routine  Reference  Section.) 
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Apple  GEOS  uses  over  7K  of  tables  to  efficiently  map  pixel  positions  to  screen  memory  bytes, 
thereby  avoiding  time-consuming  shift  and  convert  algorithms.  If  an  application  writes  directly  to 
screen  memory,  keep  in  mind  that  it  will  need  to  handle  this  pixel  conversion  manually.  Also, 
before  writing  directly  to  the  Apple  screen,  be  sure  to  call  TempHideMouse  to  temporarily 
disable  the  virtual  sprites  (for  more  information,  refer  to  TempHideMouse  in  Routine  Reference 
Section). 

Porting  Considerations  and  Techniques 

Outside  of  the  normal  considerations  for  porting  a  GEOS  application  from  one  machine  to  another, 
there  are  a  few  additional  elements  which  pertain  specifically  to  graphics. 

Apple  GEOS  and  GEOS  128  Virtual  Sprites 

Apple  GEOS  and  GEOS  128  (in  80-column  mode)  render  sprites  entirely  in  software  by  modifying 
the  actual  bitmap  screen.  (GEOS  64  and  GEOS  128  in  40-column  mode,  use  the  hardware  sprite 
capabilities  of  the  VIC  chip.)  In  order  to  properly  treat  these  virtual  sprites  as  if  they  were  apart 
from  the  bitmap  screen,  they  must  be  erased  before  any  graphic  operation,  whether  drawing, 
testing,  imprinting,  or  recovering,  is  done.  To  do  this,  Apple  GEOS  and  GEOS  128  provide  the 
TempHideMouse  routine  to  temporarily  remove  all  sprites.  The  sprites  are  not  redrawn  until  the 
application  returns  to  MainLoop.  Normal  GEOS  graphics  and  text  routines  will  automatically  call 
TempHideMouse;  only  applications  that  are  directly  accessing  the  foreground  screen  area  need 
call  TempHideMouse.  For  more  information,  refer  to  TempHideMouse  in  the  Routine 
Reference  Section  "Software  Sprites"  in  Chapter  @ SPRITE®. 

GEOS  128  X-position  and  Bitmap  Doubling 

Because  the  GEOS  128  80-column  bitmap  screen  has  a  horizontal  resolution  exacdy  twice  that  of 
GEOS  64  (640  vs.  320),  GEOS  128  supports  the  ability  to  automatically  double  the  x- 
coordinate(s)  of  graphic  and  text  objects,  and  the  width  of  bitmap  objects,  by  setting  spetial  bits  in 
the  x-position  and  width  calling  parameter(s).  This  allows  the  visual  elements  of  a  GEOS  64 
application  to  run  in  80-column  mode  under  GEOS  128  with  a  minimum  of  effort.  The  special  bits 
can  also  be  added  at  run-time  to  dynamically  configure  a  program  to  run  correctly  under  both 
GEOS  64  and  GEOS  128.  X-position  and  bitmap  doubling  is  supported  by  nearly  every  GEOS 
128  routine  that  writes  to  the  screen  (including  text,  dialog  lx)x,  and  icon  routines). 

The  following  constants  may  be  bitwise  or*ed  into  GEOS  128  x-coordinates  and  bitmap  widths  to 
take  advantage  of  the  automatic  80-column  doubling  features: 


12 


Graphics  Routines  (fourth  edit  /  MGL) 


4/24/88         8:13  PM 


DOUBLE^W 

For  doubling  word-length  values.  Normal  x- 
coordinates,  such  as  those  passed  to  Rectangle  and 
DrawPoint. 

DOUBLETS 

For  doubling  byte-length  values.  A  byte-lei||Mt  value  is 
either  a  card  x-position  or  a  card  width,  botn  of  which 
apply  almost  exclusively  to  bitmap  routines,  such  as 

R iftTiJi nT In  nnH  Ritmanr^lin 
u  11  Jii<i p u p  diivi  JLyiiiiiapv^ii |j. 

ADDl^W 

Used  in  conjunction  with  DOUBLE_W;  adds  one  to 
a  doubled  word-length  value.  This  allows  addressing 
odd-coordinates,  as  when  drawing  a  one-pixel  frame 
around  a  filled  rectangle. 

Used  in  conjunctioij-with  DPUBLEJB;  ad^s-one  u>a 
^oublpd:Dyte  lengtn  valupr^  / 

These  doubling  bits  have  no  effect  when  GEOS  128  is  in  40-column  mode  but  come  to  life  when 
GEOS  128  is  in  80-column  mode.  For  example,  the  following  code  fragment  will  frame  a  filled  V^>5i^>^, 
rectangle.  It  will  appear  similarly  in  both  40-  and  80-column  modes. 

Example: 


XI 

=  35 

;left 

edge 

X2 

«  301 

/ right 

edge 

Yl 

=  40 

/top  edge 

Y2 

=  100 

/bottom  edge 

;  Draw 

a  filled 

rectangle  using  the 

current 

pattern 

jsr 

i_Rectangle. 

/inline  call 

.byte 

Yl   .  . 

;yi 

.byte 

Y2 

;y2 

.word 

(X1|D0UBLE_W|ADD1_W) 

/xl  with  doubled 

width 

.word 

(X2|D0UBLE__W) 

/x2  with  doubled 

width 

jsr 

i^FrameRect angle 

/inline  call 

.byte 

Yl 

;yi 

.byte 

Y2 

;y2 

.word 

(X1|D0UBLE__W) 

/xl  with  doubled 

width 

.word 

(X2I DOUBLE  WIADDl  W) 

/x2  with  doubled 

width 

.byte 

$ff 

/solid  line  pattern 

rts 

/  exit 

+  space  on  left  for  frame 


+  offset  for  frame 


NOTE:  GEOS  128  filters  all  word-length  x-coordinates  (but  not  widths  or  byte-length  x- 
coordinates)  through  the  routine  NormalizeX  to  process  the  doubling.  For  more 
detailed  information  on  how  this  routine  works,  refer  to  its  documentation  in  this 
chapter.  NormalizeX  will  also  double  signed  x-coordinates.  If  the  x-coordinate  is  a 
signed  number  (like  you  might  pass  to  SmallPutChar),  then  the  double  bits  must  be 

 exclusive-or'ed  into  the  x-coordinate  parameters  rather  than  simply  ofed.  


The  graphic  elements  of  existing  GEOS  64  applications  can  be  ported  to  run  under  GEOS  128  with 
a  minimum  of  effort  by  taking  advantage  of  the  GEOS  128  doubling  bits.  However,  once  the 
doubling  bits  have  been  installed,  the  application  will'  no  longer  run  under  GEOS  64.  The  simplest 
approach  to  this  problem  is  to  have  two  entirely  different  applications.  One  designed  to  run  under 
GEOS  64  and  the  other  designed  to  run  under  GEOS  128.  The  doubling  bits  may  be  controlled  at 
assembly-time  with  conditional  assembly,  as  the  following  example  illustrates. 

Example: 
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DblDemol : 

;Will  assemble  differently  depending  on  the  status  of  the  C64  and  C128  assembly 
/constants.  If  assembling  for  GEOS  64,  doubling  constants  will  be  set  to  zero  so 
;that  they  will  not  affect  the  x-poisitions.  If  assembling  for  GEOS  64,  doubling 
/constants  will  be  set  according  to  geosConstants  file  so  that  graphic  operations 
;will  double  automatically  in  128  mode. 


.if         (C128  C64) 
.if  !C128 


DOUBLE_B 
ADDl  e  


DOUBLE__W 
ADDl  W 


;C64/C128  flags  must  be  mutually  exclusive! 

;if  not  assembling  for  GEOS  128,   force  doubling 
/constants  to  harmless  values  so  GEOS  64  graphics 
/routines  don't  get  confused. 


=  $00 


-=  $0000 
=  $0000 


.endif 


BM__XPOS 
BM  YPOS 


=  (32/8) 
«  20 


/byte  x-position  of  bitmap  (40-col) 
/y-position  of  bitmap 


Bitmap: 


BM_WIDTH 
BM  HEGHT 


PicW 
PicH 


/byte  bitmap  width  (40-col) 
/bitmap  height 


FPATTERN 
DoBmap: 


%11111111       /pattern  for  surrounding  frame 


/Place  the  bitmap  on  the  screen,  loading  the  registers  with 


/inline 

data 

(note  double-width  settings) . 

jsr 

i__BitmapUp 

/inline  call 

.word 

Bitmap 

/bitmap  address 

.byte 

(BM_XPOS|DOUBLE_B) 

/xpos 

.byte 

BM^YPOS 

/ypos 

.byte 

(BM_WIDTH 1  DOUBLETS) 

/width 

.byte 

BM_HEIGHT 

/ height 

90$: 

rts 

/exit 

•  else 

/  (both 

C128  &  C64  constants  were  both  true  or  both  false) 

.echo 

"DblDemo  routin^'^Ursigned  to  assemble  for  both  GEOS 

.endif 

r\ 

Designing  an  application  so  that  it  runs  well  under  both  GEOS  64  and  GEOS  128  is  a  more 
difficult  task.  It  usually  involves  using  self-modifying  code:  part  of  the  initialization  code  for  each 
module  can  check  the  version  of  GEOS  it  is  running  under  (use  the  Checkl28  subroutine 
illustrated  in  "GEOS  128  40/80-Column  Support"  in  this  chapter)  and  add  the  proper  doubling-bits 
to  all  relevant  x-coordinates. 
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Apple  Bitmap  Doubling  and  Aux-memory  Bitmaps 

Apple  GEOS  supports  the  ability  to  automatically  double  the  width  of  bitmap  objects  by  setting 
special  bits  in  the  x-width  calling  parameter(s).  TTiis  allows  GEOS  64  bitmaps  to  be  converted  to 
Apple  GEOS  with  a  minimum  of  effort.  By  doubling  the  width,  a  similar  appearance  can  be 
maintained.  Apple  GEOS  bitmap  routines  can  also  specify  whether  the  bitmap  data  is  in  main 
memory  or  auxiliary  memory  by  setting  special  bits  in  the  x-position  parameters.  Bitmap  doubling 
and  aux-memory  specification  applies  to  the  following  routines  and  any  other  higher-level  routines 
which  depend  on  these  for  placing  bitmaps  on  screen  (such  as  Dolcons): 

•  BitmapUp 

•  NewBitUp 

•  BitmapCIip 
•NewBitCIip 

•  BitOhterClip 

•  NewBitOtherClip 

Because  Apple  GEOS  allows  widths  specified  by  byte  values  (as  in  BitmapUp)  and  widths 
specified  by  word  values  (as  in  NewBitUp),  there  are  different  bits  and  constants  to  use  for 
doubling  the  width,  depending  on  the  number  of  bytes  (one  or  two)  in  the  parameter.  To  double 
the  widdi  of  a  bitmap,  bitwise-or  one  of  the  following  constants  into  the  width  parameter: 


d6uble  w 

For  doubling  word-length  values. 

DOUBLE  b 

For  doubling  byte-length  values. 

\ 


To  force  Apple  GEOS  to  grab  the  bitmap  data  from  auxiliary  memory,  bitwise-or  the  bitmap  x- 
position  with  one  of  the  following  values,  depending  on  whether  the  x-position  is  a  byte-length  or 
word-length  parameter: 


INAUX  B 

for  byte-length  x-position  parameters. 

iNai)X"'w 

for  word-length  x-position  parameters. 

For  more  information  on  the  bits  to  set  for  bitmap  doubling  and  auxiliary  memory  specificatiion, 
refer  to  the  documentation  of  the  specific  routines  in  Routine  Reference  Section. 

Example: 

;Put  a  bitmap  up,  using  an  address  in  auxiliary  memory  and  doubling  its  width 


LoadW  r  0 , tMyAuxBitmap 

LoadW  r3,  #  (MY^XPOS  I  INAUX__W) 

LoadB  rlH,#MY_YPOS 

LoadB  r2,#(MY_CWIDTH*8)  I  DOUBLE  I W 

LoadB  rlL,  #MY__HEIGHT 

jsr  NewBitUp 


;aux  address  of  bitmap 
; x-position  +  in-aux  flag 
;y-coordinate 

/width  =  card  width  *  8  +  doubling  bit 
/height 

;put  bitmap  on  screen 
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Points  and  Lines 


Points 

The  simplest  graphic  operation  involves  setting,  clearing,  or  testing  the  state  of  an  individual  pixel, 
or  point,  on  the  screen.  GEOS  provides  two  routines  for  working  with  points: 


•  DrawPoint 

Set  or  clear  a  single  point. 

•  TestPoint 

Test  a  single  point:  is  it  set  or  clear? 

Horizontal  and  Vertical  Lines 

Due  to  the  rectangular  nature  of  bitmapped  graphics,  horizontal  and  vertical  lines  are  inherently  fast 
and  easy  to  create  and  manipulate.  GEOS  provides  five  routines  for  working  with  horizontal  and 
vertical  lines: 


•  HorizontalLine 

Draw  a  horizontal  line  with  a  repeating  bit  pattern. 

•  VerticalLine 

Draw  a  vertical  line  with  a  repeating  bit  pattern. 

•  InvertLine 

Invert  the  pixels  in  a  horizontal  line. 

♦  ImprintLine 

Imprint  a  horizontal  line  to  the  background  buffer. 

•  RecoverLine 

Recover  a  horizontal  line  from  the  background  buffer. 

Line  Patterns. 

Both  HorizontalLine  and  VerticalLine  use  a  byte-sized  bit  pattern  when  creating  the  line.  Each 
bit  in  the  pattem  byte  represents  a  pixel  in  the  line:  wherever  a  one  appears  in  the  pattern  byte,  the 
corresponding  pixel  will  be  set,  and  wherever  a  zero  appears  ,  the  corresponding  pixel  will  be 
cleared.  This  allows  lines  which  vary  from  solid  (all  Ts)  to  dashed  (a  mixture  of  Ts  and  O's)  to 
clear  (all  O's).  Note:  this  concept  of  a  line-pattem  is  different  from  die  8x8  GEOS  fill  patterns  used 
for  rectangles. 

Bits  in  the  pattem  byte  are  used  left-to-right  for  horizontal  lines  and  top-to-bottom  in  vertical  lines, 
where  bit  7  is  at  the  left  and  the  top,  respectively.  A  bit  pattem  of  %1111(X)(X)  would  create  a 
horizontal  line  like: 

mmKErnjmmMjjn 

and  a  vertical  line  like: 
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I 

I 

The  pattern  byte  is  always  drawn  as  if  aligned  to  an  eight-pixel  boundary.  If  the  endpoints  of  a  line 
do  not  coincide  with  eight-pixel  boundaries,  then  bits  are  masked  off  the  appropriate  ends.  The 
effect  of  this  is  that  a  pattern  is  always  aligned  to  specific  pixels,  regardless  of  the  endpoints  and 
that  adjacent  lines  drawn  in  the  same  pattern  will  line  up.  That  is,  positions  0,  8,  16,  24,  etc.  will 
always  depend  on  pattern  bit  7,  and  positions  1,9, 17, 25,  etc.  will  always  depend  on  pattern  bit  6. 

NOTE:  Because  of  the  internal  memory  layout  of  screen  memory,  horizontal  lines  will  often 
 draw  up  to  eight  times  faster  than  vertical  lines.  


Diagonal  Lines 

For  the  same  reason  that  bitmap  displays  are  well-suited  for  displaying  horizontal  and  vertical 
lines,  they  are  ill-suited  for  displaying  diagonal  Hnes.  A  smooth,  even-density  line  cannot  be  drawn 
diagonally  between  two  points  (except  at  45-degree  angles)  —  the  points  on  the  line  must  be 
approximated  in  a  stairstep  fashion: 


GEOS  provides  one  routine  for  drawing  and  recovering  a  line  between  two  arbitrary  points: 

pT)rawLine  Draw  or  recover  a  line  between  any  two  points. 

DrawLine  does  not  utilize  a  pattern  byte;  it  will  either  set  or  clear  all  pixels  between  the  two 
endpoints. 


NOTE:  DrawLine  is  the  most  general-purpose  drawing  routine.  It  can  be  used  to  draw  single 
points  (both  endpoints  the  same),  horizontal  and  vertical  lines,  or  lines  at  arbitrary 
angles.  However,  it  is  burdened  by  this  flexibility^  making  it  appreciably  slower  than 
the  other  plotting  routines. 


Patterns  and  Rectangles 
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GEOS  uses  two  types  of  patterns:  line  patterns  and  fill  patterns.  A  line  pattern  is  a  one-byte 
repeating  pixel  pattern  used  by  routines  lUce  HorizontalLine  and  VerticalLine,  and  a  fill  pattern 
is  an  8x8  pixel  block  represented  by  eight  bytes  in  memory  and  used  by  routines  like  Rectangle. 
Line  patterns  are  discussed  in  "Points  and  Lines"  earlier  in  this  chapter.  Fill  patterns  are  discussed 
here. 

A  50%  fill  pattern  might  be  defined  by  the  following: 

.byte  %10101010 
.byte  %01010101 
.byte  %10101010 
.byte  %01010101 
.byte  %10101010 
.byte  %01010101 
.byte  %10101010 
.byte  %01010101 

The  pattern  has  alternating  set  and  clear  pixels.  Drawing  a  filled  rectangle  in  this  pattern  would 
produce  a  medium-dark  block. 

All  versions  of  the  GEOS  Kemal  contains  the  following  predefined  patterns: 
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Apple  GEOS  contains  an  additional,  user-defined  pattern  which  is  left  for  the  application  to 
modify. 

Fills  occur  in  the  current  pattern.  The  current  pattern  can  be  changed  with  the  following  routine: 

hSetPattern  Set  the  current  pattern. 

To  use  one  of  the  system  patterns,  the  application  would  first  call  SetPattern  with  the  appropriate 
pattern  number.  SetPattern  calculates  tihe  proper  pattern  address,  the  adckess  of  the  eight-byte 
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block,  and  places  it  in  the  GEOS  variable  curPattern  (formeriy  currentPattern).  Any 
subsequent  call  to  a  routine  which  uses  a  system  pattern  will  index  off  of  the  address  in 
curPattern  to  access  the  8x8  block.  Some  applications,  finding  the  need  to  define  their  own 
patterns,  modify  either  the  address  in  curPattern  to  point  to  their  own  eight-byte  pattern  or  use 
the  address  in  curPattern  (after  a  valid  call  to  SetPattern)  to  modify  the  GEOS  system  patterns 
directly.  This  technique  will  work  on  both  GEOS  64  and  GEOS  128,  but  will  not  on  Apple  GEOS 
because  the  patterns  are  stored  in  a  fairly  inaccessible  portion  of  memory.  Apple  GEOS  provides 
two  routines  for  accessing  and  redefing  patterns: 


•  GetPattern 

Download  a  GEOS  pattern  to  an  eight-byte  buffer. 

•  SetUserPattern 

Upload  an  eight-byte  buffer  to  a  GEOS  pattern. 

NOTE:    GEOS  does  not  restore  the  system  patterns  when  an  application  exits.  If  an  application 
modifies  the  patterns,  it  should  restore  them  when  it  exits  unless  it  is  desirable  for  the 
 next  application  to  inherit  the  redefined  patterns  (as  with  the  GEOS  Pattern  Editor). 


Rectangles 

Rectangles  in  GEOS  are  defined  by  their  upper-left  and  lower-right  comers.  The  upper-left  is 
usually  referred  to  as  (X1,Y1)  and  the  lower-right  as  (X2,Y2),  where  XI,  X2,  Yl,  and  Y2  are 
valid  X  and  y  screen  positions.  From  these  two  coordinates,  the  rectangle  routines  can  determine 
the  coordinates  of  the  other  two  comers: 


(XI, YD 

{X2,Y1) 

(XI, Y2) 

(X2,Y2) 

GEOS  provides  five  routines  for  dealing  with  rectangular  regions: 


•  Rectangle 

Draw  a  solid  rectangle  using  the  current  fill  pattern. 

♦  FrameRectangle 

Draw  an  unfilled  rectangle  (bounding  frame). 

•  InvertRectangle 

Invert  the  pixels  in  a  rectangular  area. 

•  ImprintRectangle 

Imprint  a  rectangular  area  to  the  background  buffer. 

•  RecoverRectangle 

Recover  a  rectangular  area  from  the  background  buffer. 

Bit-mapped  Images 

All  graphic  picture  objects,  such  as  icons  and  Photo  Scrap  images  cut  from  geoPaint,  are  stored 
internally  in  GEOS  Compacted  Bitmap  Format  to  save  space.  When  you  paste  an  image  or  icon 
into  a  geoProgrammer  source  file,  it  is  in  compacted  bitmap  format,  and  when  you  read  a  geoPaint 
image,  it  too  is  in  compacted  bitmap  format  If  a  compacted  image  were  to  be  copied  direcdy  to  the 
screen,  it  would  very  likely  be  unrecognizable.  GEOS  bitmap  routines  first  decompact  the  image 
and  then  transfer  it  to  the  screen  area. 
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Standard  Bitmap  Routines 

All  versions  of  GEOS  support  the  following  bitmap  routines: 


•  BitmapUp 

Place  a  full  compacted  bitmap  on  the  screen. 

•  BitmapClip 

Place  a  rectangular  subset  of  a  compacted  bitmap  on  the  screen. 

•  BitOtlierCIip 

Special  version  of  BitMapClip  which  uses  an  application- 
defined  routine  to  collect  the  compacted  bitmap  data  a  byte  at  a 
time,  allowing  the  image  to  come  from  disk  or  other  I/O  device. 

GEOS  bitmaps  are  compacted  from  the  GEOS  virtual  screen  format  rather  than  the  internal  machine 
format.  Because  the  standard  bitmap  routines  deal  with  byte-sized  chunks  (eight-pixels  at  a  time), 
the  following  apply: 

♦  Horizontally,  the  bitmap  occupies  pixels  up  to  the  nearest  eight-pixel  (byte)  boundary. 
That  is:  a  bitmap  of  five  pixels  is  extended  to  eight  and  a  bitmap  of  30  pixels  is  extended  to 
32  pixels.  Bitmaps  which  are  not  evenly  divisable  by  eight  (in  the  horizontal  direction)  are 
usually  padded  with  zero  bits. 

•  Bitmaps  can  only  be  placed  at  eight-pixel  intervals  on  the  x-axis  (0,  8,  16...).  This 
limitation  does  not  apply  to  the  y-axis. 

Apple  GEOS,  however,  provides  two  extended  bitmap  routines  for  overcoming  these  limitations. 
These  routines  might  eventually  be  incorporated  into  GEOS  64  and  GEOS  128. 

Apple  GEOS  Extended  Bitmap  Routines 

The  Apple  GEOS  extended  bitmap  routines  allow  bitmaps  of  any  pixel  width  and  do  not  force  the 
bitmap  to  be  drawn  on  eight-pixel  x-axis  boundaries.  These  bitmaps  are  still  compacted  in  byte- 
sized  chunks,  but  by  specifying  a  pixel  width,  any  extra  bits  at  the  end  of  the  last  byte  are  ignored 
(masked  out)  when  the  bitmap  is  displayed.  Apple  GEOS  offers  three  new  bitmap  routines: 


•  NewBitUp 

Pixel  width  and  positioning  version  of  BitmapUp. 

•  NewBitCIip 

Pixel  width  and  positioning  version  of  BitmapClip. 

•  NewBitOtherClip 

Pixel  width  and  positioning  version  of  BitOtherClip. 

GEOS  Compacted  Bitmap  Format 

The  GEOS  compacted  bitmap  format  relies  on  the  observation  that  pixel  patterns  in  bitmap  images 
are  frequently  repetitive.  If  you  were  to  examine  a  rectangular  area  of  the  screen  (in  GEOS  linear 
bitmap  format)  it  would  often  be  the  case  that  adjacent  bytes  would  be  identical.  The  compacted 
bitmap  format  encodes  this  redundancy  into  groups  of  bytes  called  packets.  Each  packet  can 
decompress  to  a  large  number  of  bytes  in  the  actual  bitmap. 
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Packet  Format 

Each  packet  in  a  GEOS  compacted  bitmap  follows  a  specific  foraiat.  The  first  byte  of  each  packet 
is  called  the  count  byte  and  is  part  of  the  packet  header.  Depending  on  its  value,  it  has  the 
following  significance: 


COUNT 

(HEX) 

SIGNIFICANCE 

0 

($00) 

reserved  for  future  use. 

1-127 

($00-$7f) 

repeat:  repeat  the  following  byte  count  times.  The  total  length  of 
this  packet  is  two  bytes  and  decompresses  to  count  bytes  in  the 
actual  bitmap. 

128 

($80) 

reserved  for  future  use. 

129-219 

($81-$db) 

unique:  use  the  next  count-128  bytes  literally.  The  total  length 
of  this  packet  is  (count-128)+l  or  count-127  bytes  and 
decompresses  to  count-128  bytes. 

220 

($dc) 

reserved  for  future  use. 

221-255 

($dd-$ff) 

bigcount:  the  next  byte  is  a  bigcount  value  in  the  range  2 
through  255.  The  following  count-220  bytes  comprise  data  in 
repeat  and  unique  format  that  should  be  repeated  bigcount 
times.  The  total  length  of  this  packet  depends  on  the  decompacted 
size  of  tht.repeat  and  unique  packets.  A  bigcount  cannot 
containt  another  bigcount. 

Decompaction  Walkthrough 

Given  the  following  compacted  data: 

.byte  25,  0,  133,  240,  220,  10,  0,  7,  224,  4,  3,  10,  5,  3 

The  decompaction  routine  would  interpret  it  like  this: 

repeat:  the  decompaction  routine  encounters  the  count  value  25.  Since  it  is  in  the  range 
1-127,  the  following  byte  (0),  is  repeated  25  times: 

0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0,  0 

133,  240,  220,  10,  0,  7"! 

unique:  the  next  packet  begins  with  a  count  of  133,which  is  in  the  range  129-219,  The 
next  133-128  =  4  bytes  are  used  once  each: 

240,  220,  10,  0,  7 

1224,  4,  3,  10,  5,  3  | 

bigcount:  the  final  packet  begins  with  a  count  of  24  which  is  in  the  range  221-255. 
This  signals  a  two  byte  header  and  the  following  byte,  the  bigcount,  is  4.  These  two 
bytes  are  interpreted  to  mean  repeat  the  next  224-220  =  4  bytes  four  times.  The  next  four 
bytes,  however,  are  expected  to  be  in  the  unique  and  repeat  compacted  formats.  In  this 
case,  its  3,10  (repeat:  10  three  times)  and  5,3  (repeat:  3  five  times),  which  in  turn  are 
repeated  four  times: 
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10,  10,  10  ,3,  3,  3,  3,  3,  10,  10,  10  ,3,  3,  3,  3,  3,  10,  10,  10  ,3,  3,  3,  3,  3,  10, 
10,  10  ,3,  3,  3,  3,  3 


Compacting  Strategy 

The  easiest  way  to  compact  a  bitmap  image  is  to  let  geoPaint  do  it  for  you  by  cutting  the  image  out 
as  a  photo  scrap  and  pasting  it  directly  into  your  geoProgrammer  source  code.  Sometimes  this 
method  is  impractical  and  you  will  want  to  compress  images  directly  from  within  an  application. 
The  following  subroutine  can  be  used  to  compact  bitmap  data: 

.if  (0) 

*»««**«***★**«**««********★***★***«★********«**«***«* 

BitCompact 

«*««*■««*★*★★*«****»*********«★★*★**★«*★***★★★***** 

DESCRIPTION: 

Converts  linear  bitmap  data  into  compacted  bitmap  format,  suitable 
for  passing  to  routines  such  as  BitmapDp. 

When  compacting  bitmaps  directly  from  screen  memory,  the  data  must 
must  first  be  converted  from  the  internal  screen  format  to  linear 
bitmap  format.  The  left  edge  of  the  source  bitmap  must  start  on  a 

card  boundary  and  the  right  edge  must  extend  to  the  end  of  another,....-^  .  ^ 

card  boundary.    (Under  Apple  GEOS,  strictly  speaking,  the  wrg^^t  "Cdge^  need 
not  fully  extend  to  a  card  boundary  because  the  new  bitmap  routines 
(NewBitUp,  NewBitClip,  etc.)  can  mask  bits  at  the  right  edge.) 

This  bitmap  data  must  then  be  converted  to  a  linear  format,  where 
the  first  byte  represents  the  first  eight  pixels  of  the  upper-left 
corner  of  the  bitmap,  the  next  byte  represents  the  next  eight  pixels 
and  so  on  to  the  right  edge  of  the  bitmap.  The  byte  following  the 
last  byte  in  a  single  line  of  a  bitmap  is  the  first  byte  of  the  next 
line.    (The  actual  dimensions  of  the  bitmap  will  be  reconstructed  from 
the  WIDTH  and  HEIGHT  parameters  passed  to  the  bitmap  display  routine. 

To  convert  from  internal  screen  format  to  linear  bitmap  format: 

C64:       Set  dispBufferOn  appropriately  (to  reflect  which 
screen  buffer  to  grap  data  from)  and... 


( 


7 


Cnvrt40: 

Idx 

yPos 

;  get  y  coord  of  top  of  bitmap 

jsr 

GetScanLine 

;  use  it  to  calc  screen  ptrs 

Ida 

xPos 

;  get  x  pixel  coord  (lo  byte) 

and 

#%11111000 

;  strip  off  3  bits  for  card  x-position 

clc 

;  Add  card  offset  to 

adc 

r5L 

;  base  pointer  (lo  byte  first) 

sta 

r5L 

Ida 

xPos+1 

;   (hi  byte  also) 

adc 

r5H 

sta 

r5H 

;At 

this  point,  (r5) 

points  to  the  first  byte  in 

;the 

bitmap  (upper-left  corner) . 

Now  step  through  each  byte  in  this  scanline  by  adding 
8  to  the  pointer  in  r5  (compensating  for  the  card  architecture) 
to  get  to  the  next  byte,  and  repeat  this  process  for  each  line 
in  the  bitmap  (incrementing  yPos  appropriately  for  each  scanline)  , 


C128:      (40-column,  same  as  C64;  80-column,  read  on...) 

Conveniently,  the  80-column  data  is  already  in  linear  bitmap 
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format.  The  data,  will  probably  be  coming  from  the 
background  buffer  because  the  foreground  screen  is 
entirely  contained  on  the  VDC  chip's  internal  RAM  and 
is  difficult  to  access... 


CnvrtSO: 

bit  graphicsMode 

bpl  Cnvrt4  0 

PushB  dispBufferOn 

LoadB  dispBufferOn, #ST_WR 

Idx  yPos 

jsr  GetScanLine 

Movew  xPos,rO 

Idx  #rO 

Idy  #3 

jsr  DShiftRight 

AddW  r0,r6 

;At  this  point  (r6)  points 
/bitmap. 


;  make  sure  in  80-col  mode 
;  handle  40  like  C64 
;  save  current  dispBuffer 
BACK  /force  use  of  back  buffer 
get  y  coordinate 
use  it  to  calc  screen  ptrs 
copy  x-position  to  zp  work  reg 
divide  rO  by  8 
(shift  right  3  times) 
this  gives  us  the  card  offset 
add  card  (byte)   offset  to  scanline  addr 
to  the  first  byte  of  the 


Now  step  each  byte  in  this  scanline  by  adding 
1  to  the  pointer  in  r6  to  get  to  the  next  byte, 
and  repeat  this  process  for  each  line  in  the 
bitmap  (incrementing  yPos  appropriately) . 


Apple:  Use  the  Apple  GEOS  Kernal  routines  ReadScanLine 

and  ReadBackLine  to  convert  the  internal  Apple 
screen  format  into  linear  bitmap  format.  Nice  and  simple. 

CALLED  BY: 


PASSED: 

rO  Pointer  to  destination  buffer  to  store  compacted  data 

(this  buffer  must  be  at  least  1  and  1/64  of  size  of  the 
uncompacted  data  because  it  is  possible,  but  unlikely,  that 
the  compacted  data  will  actually  be  larger  than  the  ucompacted 
data) . 

rl  Pointer  to  linear  bitmap  data  to  compact. 

r2  #  of  bytes  to  compact. 


RETURNS : 

rO         Points  to  byte  following  last  byte  in  compacted  data. 


DESTROYED: 

a, X, y, rl-r6 


PSEUDO  CODE  /  STRATEGY: 

Starts  with  the  first  source  byte  and  counts  the  number  of  identical  bytes 
following  it  to  determine  whether  to  generate  a  UNIQUE  or  REPEAT  packet.  If 
there  are  three  or  less  identical  bytes  in  a  row,  a  UNIQUE  packet  is  generated, 
four  or  more  generates  a  REPEAT  packet.  The  packet  is  placed  in  the  destination 
buffer  and  this  process  is  then  repeated  until  all  bytes  in  the  source  buffer 
have  been  compressed. 

KNOWN  BUGS  /  SIDE  EFFECTS  /  IDEAS: 

Only  uses  the  UNIQUE  and  REPEAT  compaction  types.  The  BIGCOUNT  compaction  type  is 
such  that  it  is  difficult  to  determine  the  compaction  payoff  point.  BIGCOUNT  could 
be  used  to  compress  adjacent  scanlines  that  are  identical  because  this  type  of  check 
would  be  trivial.  The  basic  scanline  could  be  compressed  with  UNIQUE  and  REPEAT,  then 
duplicated  by  placing  it  inside  a  BIGCOUNT. 

This  routine  is  not  limited  to  compressing  bitmap  data.  In  fact,  it  works  quite 
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well  on  any  data  where  strings  of  identical  bytes  are  common  (e.g.,   fonts).   It  does 
not,  for  example,  compress  text  very  efficiently.  A  Huffman-based  algorithm  yields 
better  results. 


ir********* 


t  *  *  * 'k  te  ic  *  *  it -i 


(mgl) 


.endif 


MAX__R£?£AT 
MAXJJNIQUE 
UNIQ  THRESH 


127 

91 

3 


maximum  repeat  COUNT  value 
maximum  unique  COUNT  value 

byte  count  threshold,  beyond  which  a  REPEAT  type 
should  be  used  instead  of  UNIQUE. 


BitCompact : 
10$: 


jsr 
cmp 
ble 

sta 

Idy 

sta 

Ida 

iny 

sta 

AddVW 

bra 

20$: 


jsr 

Idy 
ora 
sta 

Ida 

iny 

sta 

cpy 

bne 

inc 

AddBW 

dec 


30$: 


100$: 


AddBW 

SubBW 

Ida 

ora 

bne 

rts 


CountRepeat 

#UNIQ_THRESH 

20$ 


r5L 
#0 

(rO)  . 
(rl)  , 


(rO),y 

#2,r0 

100$ 


GetUnique 
#0 

#$80 
(rO)  ,y 

(rl)  ,y 

(rO),y 

r5L 

30$ 

r5L 

r5L, rO 

rSL 


r5L,rl 

r5L,r2 

r2L 

r2H 

10$ 


rl  =  current  addr  in  source  buffer 

rO  =  current  addr  in  destination  buffer 

r2  =  #  bytes  left  in  source 

count  the  #  of  identical  bytes  here 

Enough  repeats  to  justify  REPEAT  type? 

No,  go  use  UNIQUE 

yes,  use  REPEAT  (A  =  #  to  repeat) 

store  repeat  #  for  later 

init.  index  into  buffers 

store  repeat  #  to  destination 

get  repeat  value 

point  to  next  byte  in  dest  buffer 
store  to  destination  buffer 
move  up  dest .  pointer 
exit. 

use  UNIQUE 

Calc  #  of  unique  bytes  to  use 
(A  =  number  of  unique) 
init.  index  into  buffers. 

convert  unique  count  to  packet  count  value 
store  to  dest. buffer 

get  first  unique  value 

increment  pointer  pointer 

store  to  destination  buffer 

done  yet?  (r5L  «  repeat  #) 

loop  till  done  copying 

convert  to  #  to  add  to  dest  pointer 

move  up  destination  pointer 

correct  bac)c  to  #  done 

fall  through  to -exit 

move  up  source  pointer 

subtract  off  #  left  in  source  buffer 

check  for  zero  bytes  left 

more  to  do? 

if  so,  loop 

else,  exit. 


CountRepeat : 


Idy 
Idx 


#0 
#0 


rl  «  current  pointer  into  source  buffer 
rO  =  current  pointer  into  destination  buffer 
r2  «  number  of  bytes  left  in  source 
initialize  relative  buffer  index 
initalize  current  repeat  count 
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Ida 

(rl),y 

get  first  byte 

sta 

r6L 

keep  in  r6L.  This  is  the  byte  we're  trying 

to  match. 

10$: 

Ida 

r2H 

more  than  255  bytes  left  in  source? 

bne 

20$ 

if  so,  ignore  #  check 

cpx 

r2L 

else,  are  we  at  the  last  byte? 

beq 

90$ 

if  so,  exit 

20$: 

cpx 

#MAX__REPEAT 

check  repeat  count  with  max  #  of  repeats 

beq 

90$ 

if  at  maximum,  branch  to  exit. 

Ida 

(rl),y 

does  it  actually  match? 

cmp 

r6L 

check  against  1st  byte 

bne 

90$ 

if  no  match,  exit. 

inx 

else,  we  found  a  match,  increment  repeat  count 

iny 

move  to  next  byte  in  source 

;NOTE 

—  following  branch  changed  to 

save  a  byte,  y  is  never  incremented  to  $00. 

bra 

10$ 

and  loop  to  check  it 

bne 

10$  , 

branch  always...  iny  above  will  always  clear  z 

90$: 

txa 

return  repeat  count  in  A 

rts 

exit 

GetUnique: 

PushW 

rl 

Save  orig  pointer 

LoadB 

r5L,#0 

start  none  unique 

10$: 

inc 

r5L 

•  do  one  more  unique 

Idx 

r5L 

•  get  #  unique  so  far 

Ida 

r2H 

•  lots  left? 

bne 

20$ 

•  if  so,  skip  end  check 

cpx 

r2L 

•  all  of  them? 

beq 

90$ 

•  if  yes,  then  that  many 

20$: 

cpx 

#MAX_UNIQUE 

?  max  #  unique 

beq 

90$ 

?  if  full,  do  them 

AddVW 

#l,rl 

;  move  up  a  byte 

jsr 

CountRepeat 

;  how  many  of  the  following  bytes  are  repeats? 

cmp 

#UNIQ  THRESH 

?  Enough  to  warrant  a  REPEAT  packet? 

ble 

10$ 

;  No,  go  stuff  them  in  this  UNIQUE  packet 

;  Yes,  close  this  UNIQUE  packet. 

90$: 

PopW 

rl 

;  retrieve  start  pointer 

Ida 

r5L 

;  get  #  to  do  unique 

rts 

Direct  Screen  Access  and  Block  Copying 


Direct  Screen  Access 

One  purpose  of  an  operating  system  such  as  GEOS  is  to  insulate  the  application  from  the 
peculiarities  of  the  machine  it  is  running  on,  allowing  the  programmer  to  worry  more  abot  how  the 
application  will  function  than  how  it  will  interact  with  the  hardware.  However,  because  of  the 
complexity  of  GEOS  graphics  routines,  it  is  sometimes  necessary,  for  performance  reasons,  to 
bypass  the  operating  system  and  manipulate  the  screen  memory  directly.  Although  this  practice  is 
not  recommended  —  it  increases  portability  problems,  defeating  much  of  the  purpose  of  a  GEOS 
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—  it  is  a  reality.  And  with  that  in  mind,  Berkeley  Softworks  built  routines  into  GEOS  to  facilitate 
direct  screen  access.  The  following  routine  exists  in  all  versions  of  the  Kemal: 

I  •  GetScanLine  Calculate  the  address  of  the  first  byte  of  a  particular  screen  line. 

And  these  two  additional  routines  exist  in  Apple  GEOS: 


•  GetScreenLine 

Copy  a  horizontal  line  (in  internal  format)  from  the  screen  to  an 
application's  buffer. 

•  PutScreenLine 

Copy  a  horizontal  line  (in  internal  format)  from  an  application's 
buffer  to  the  screen. 

GetScreenLine  and  PutScreenLine  are  intended  to  let  the  application  directly  access  the  Apple 
double  hi-res  screen  without  worrying  about  bank  switching  on  alternate  bytes.  The  screen  is 
treated  as  a  contiguous  block,  as  if  the  alternating  bytes  in  the  two  memory  banks  were  actually 
adjacent  in  memory.  These  routines  are  not  well-suited  for  scrolling  large  regions  (they  are  too 
slow),  but  are  sufficient  for  drawing  with  small  brushes.  For  scrolling,  use  the  block  copy 
routines. 

Linear  Bitmap  Conversion  (Apple  GEOS) 

Because  the  Apple's  pixel  memory  mapping  scheme  is  so  convoluted,  Apple  GEOS  provides 
routines  to  convert  a  line  of  data  (in  Apple's  internal  format)  to  linear  bitmap  data,  where  pixels 
occupy  contiguous  bits  in  contiguous  bytes: 


•  ReadScanline 

Translates  a  screen  line  from  the  foregorund  screen  from  Apple 
internal  format  to  linear  bitmap  format. 

•  ReacBackLine 

Translates  a  screen  line  from  the  background  buffer  from  Apple 
internal  format  to  linear  bitmap  format. 

Although  it  would  seem  that  routines  which  translate  in  the  other  direction  —  from  linear  bitmap 
format  to  Apple  format  —  are  necessary,  BitmapUp  can  be  used  for  this  purpose.  Merely 
prepend  a  70  to  the  front  of  the  linear  bitmap  and  call  BitmapUp  as  if  the  line  were  a  bitmap  70 
bytes  wide  and  one  pixel  high. 

Block  Copy  and  Scrolling  (Apple  GEOS) 

Apple  GEOS  also  extends  the  direct  screen  access  facilities  by  offering  three  block  copy  routines 
which  are  useful  for  scrolling  and  moving  rectangular  areas  of  the  screen: 

•  CopyLine  Copies  a  horizontal  line  from  one  area  of  the  foreground  screen  to 

another.  

"^opyScreenBlock  Copies  a  rectangular  area  from  one  part  of  the  screen  to  another. 

♦  CopyFuIIScreen     Copies  a  rectangle  of  the  full  width  of  the  screen  (but  of  variable 

height)  to  another  position  vertically. 

Although  these  routines  deal  directly  with  the  screen,  the  screen  architecture  is  actually  transparent 
to  the  application.  Therefore,  future  versions  of  GEOS  may  implement  these  functions. 
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Special  Graphics  Related  Routines 

GEOS  provides  a  few  graphics-related  routines  which  don't  fit  nicely  into  any  other  category: 


•  GraphicsString 

Execute  a  string  of  graphics  commands. 

•  DivideBySeven 

Quickly  divide  a  screen  coordinate  by  seven  for  direct  screen 
access  (Apple  GEOS  only). 

•  NormalizeX 

Adjust  an  x-coordinate  (under  GEOS  128  only)  to  compensate  for 
the  higher-resolution  80-column  mode. 

•  SetNewMode 

Change  GEOS  128  graphics  mode  (40/80-column). 
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Icons,  Menus,  and  Other  Mouse  Presses 


When  the  user  clicks  the  mouse  button,  GEOS  determines  whether  the  mouse  pointer  was 
positioned  over  an  icon,  a  menu  item,  or  some  other  region  of  the  screen.  GEOS  has  a  unique 
method  of  handling  a  mouse  press  for  each  of  these  cases.  If  the  user  pressed  on  an  icon,  GEOS 
calls  the  appropriate  icon  event  routine.  If  the  user  pressed  on  a  menu,  GEOS  opens  up  a  sub- 
menu or  calls  the  appropriate  menu  event  routine,  whichever  is  applicable.  And  if  the  user  pressed 
somewhere  else,  GEOS  calls  through  otherPressVector,  letting  the  application  handle  (or 
ignore)  these  "other"  mouse  presses. 

Icons 

When  you  open  a  disk  by  clicking  on  its  picture,  delete  a  file  by  dragging  it  to  the  trash  can,  or 
click  on  the  CANCEL  button  in  a  dialog  box,  you  are  dealing  with  iconSy  small  pictorial 
representations  of  program  functions.  A  GEOS  icon  is  a  bitmapped  image,  whether  the  picture  of  a 
disk  or  a  button-shaped  rectangle,  that  allows  the  user  to  interact  with  the  application.  When  the 
application  enables  icons,  GEOS  draws  them  to  the  screen  and  then  keeps  track  of  their  positions. 
When  the  user  clicks  on  an  icon,  an  icon  event  is  generated,  and  the  application  is  given  control 
with  information  concerning  which  icon  was  selected 

Icon  Table  Structure 

The  information  for  all  active  screen  icons  is  stored  in  a  data  structure  called  the  icon  table.  GEOS 
only  deals  with  one  icon  table  at  a  time.  The  icon  table  consists  of  an  icon  table  header  and  a 
number  of  icon  entries.  The  whole  table  is  stored  sequentially  in  memory  with  the  header  first, 
followed  by  the  individual  icon  entries. 

Icon  Table  Header 

The  icon  table  header  is  a  four  byte  structure  which  tells  GEOS  how  many  icons  to  expect  in  the 
structure  and  where  to  position  the  mouse  when  the  icons  are  enabled.  It  is  in  the  following  format: 

Icon  Table  Header: 


Index 

Constant 

Size 

Descriptibn 

+0 

OFF_LNUM 

byte 

Total  number  of  icons  in  this  table. 

+1 

OFFJ.MX 

wad 

Initial  mouse  x-posidon.  If  $0000,  mouse  positiion  will  not 
be  altered 

+3 

OFF_I_MY 

byte 

Initial  mouse  y-position. 

This  first  byte  reflects  the  number  of  icon  entries  in  the  icon  table  (and,  hence,  the  number  of  icons 
that  can  be  displayed).  The  table  can  specify  up  to  MAX_ICONS  icons. 

The  next  word  (bytes  1  and  2)  is  an  absolute  screen  x-coordinate  and  the  following  byte  (byte  3)  is 
an  absolute  screen  y-coordinate.  The  mouse  will  be  positioned  to  this  coordinate  when  the  icons 
are  first  displayed.  If  you  do  not  want  the  mouse  positioned,  set  the  x-coordinate  word  to  $0000, 
which  will  signal  Dolcons  to  leave  the  mouse  positions  alone. 
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Icon  Entries 

Following  the  icon  table  header  are  the  icon  entries,  one  for  each  specified  in  the  OFF_I_NUM 
byte  in  the  icon  table  header.  Each  icon  entry  is  a  seven-byte  structure  in  the  following  format: 

Icon  Entries: 


Index 

Constant 

Size 

Description 

+0 

OFFJ.PIC 

wod 

Pointer  to  compacted  bitmap  picture  data  for  this  icon.  If  set 
to  $0000,  icon  is  disabled. 

+2 

OFF  I  X 

byte 

Card  x-position  for  icon  bitmap. 

+3 

OFF  I  Y 

byte 

Y-position  of  icon  bitmap. 

+4 

OFF  I  WIDTH 

byte 

Card  width  of  icon  bitmap. 

+5 

OFF  I  HEIGHT 

byte 

Pixel  height  of  icon  biunap. 

+6 

OFFJ  EVENT 

wad 

Pointer  to  icon  event  routine  to  call  if  this  icon  is  selected. 

The  first  word  (OFF  I  PIC)  is  a  pointer  to  the  compacted  bitmap  data  for  the  icon.  The  icon  can 
be  of  any  size  (up  tolhe  full  size  of  the  screen).  If  this  word  is  set  to  NULL  ($0(X)0),  the  icon  is 
disabled. 

The  third  byte  (OFF  I  X)  is  the  x  byte-position  of  the  icon.  The  x  byte-position  is  the  x-position 
in  bytes  —  icons  are"pTaced  on  the  screen  by  BitmapUp  and  so  must  appear  on  an  eight-pixel 
boundary.  The  byte-position  can  be  calculated  by  dividing  the  pixel-position  by  eight 
(x_byte_position  =  x.pixeLposition/8). 

The  fourth  byte  (OFF_I  Y)  is  the  pixel  position  of  the  top  of  the  icon.  The  icon  will  be  placed  at 
(x_byte_position*8 ,  y_pixeLposition). 

The  next  two  bytes  (OFF J^WIDTH  and  OFF  J_.HEIGHT)  are  the  width  in  bytes  and  height 
in  pixels,  respectively.  These  values  correspond  to  the  geoProgrammer  internal  variables  PicW 
and  PicH  when  they  are  assigned  immediately  after  a  pasted  icon  image. 

The  final  word  (OFF_I_EVENT)  is  the  address  of  the  icon  event  handler  associated  with  this 
icon. 

Sample  Icon  Table 

The  following  data  block  defines  three  icons  which  are  placed  near  the  middle  of  the  screen.  The 
mouse  is  positioned  over  the  first  icon: 

/SAMPLE  ICON  TABLE 

********************************************** 

;Icon  positions  and  bitmap  data 

I__SPACE  -  1  /space  between  our  icons  (in  cards) 

Paint Icon: 


PAINTW  -  PicW 
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PAINTH  »  PicH 
PAINTX  =  16/8 
PAINTY  «  80 

Writelcon : 


WRITEW  =  PicW 
WRITER  =  PicH 

WRITEX  "  PAINTX  +  PAINTW  +  I_SPACE 
WRITEY  =  PAINTY 

Publishlcon : 


PUBLISHW 
PUBLISHH 
PUBLISHX 
PUBLISHY 


PicW 
PicH 

WRITEX  +  WRITEW  +  I__SPACE 
WRITEY 


;The  actual  icon  data  structure  to  pass  to  Dolcons  follows 
IconTable: 


I_header : 

.byte 
.word 
.byte 


NUMOFICONS 

(PAINTX*8)  +  (PAINTW*8/2) 
PAINTY  +  PAINTH/2 


number  of  icon  entries 
position  mouse  over  paint  icon 


I_entries: 
PaintlStruct : 

.word  Paintlcon 

.byte 

.byte 

.word 


PAINTX,  PAINTY 
PAINTW,  PAINTH 
PaintEvent 


; pointer  to  bitmap 
;icon  position 
;icon  width,  height 
/event  handler 


WritelStruct : 

.word  Writelcon 
.byte 
.byte 


WRITEX,  WRITEY 
WRITEW,  WRITER 


.word  WriteEvent 


/pointer  to  bitmap 
/icon  position 
/icon  width,  height 
/event  handler 


PublishlStruct : 

.word  Publishlcon 
.byte     PUBLISHX,  PUBLISHY 
.byte     PUBLISHW,  PUBLISHH 
.word  PublishEvent 


NUMOFICONS 


(*-I_entries) /lESIZE 


/pointer  to  bitmap 
/icon  position 
/icon  width,  height 
/event  handler 

/number  of  icons  in  table 


/Dummy  icon  event  routines  which  do  nothing  but  return 
V  PaintEvent: 
^'"^  WriteEvent : 
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PublishEvent : 
rts 


Installing  Icons 

When  an  application  is  first  loaded,  GEOS  will  not  have  an  active  icon  structure.  GEOS  must  be 
given  the  address  of  tiie  applications  icon  table  before  MainLoop  can  display  and  track  the  user's 
interaction  with  them.  GEOS  provides  one  routine  for  installing  icons 

I  •  Dolcons  Display  and  activate  an  icon  table.  | 

Dolcons  draws  the  enabled  icons  and  instructs  MainLoop  to  begin  watching  for  a  single-  or 
double-click  on  one.  The  icon  table  stays  activated  and  enabled  until  the  ICONS_ON_BIT  of 
mouseOn  is  cleared  or  another  icon  table  is  installed  by  calling  Dolcons  with  the  address  of  a 
different  icon  structure.  In  either  case,  the  old  icons  are  not  erased  from  the  screen  by  GEOS. 

Dolcons  will  draw  to  the  foreground  screen  and  background  buffer  depending  on  the  value  of 
dispBufferOn.  Icons  are  usually  permanent  structures  in  a  display  and  so  often  warrant  being 
drawn  to  both  screens.  If  icons  are  only  drawn  to  the  foreground  screen,  they  will  not  be  recovered 
after  a  menu  or  dialog  box. 

Example: 

;  IconsUp  Draw  and  intialize  our  icons 

•*★**★★**★****★★***★*******★**★*★*****★★**★*★***★★★*★*★*★*★*★ 

IconsUp: 

LoadB    dispBufferOn, #(ST_WR_FORE  I  ST_WR_BACK)         ;draw  to  both  buffei;s 
LoadW    rO,  #IconTable  ;point  to  icon  table 

jsr        Dolcons  /install  icons 

rts  ;exit 


Important:    Due  to  a  limitation  in  the  icon-scanning  code,  the  application  must  always  install  an 
icon  table  with  at  least  one  icon.  If  the  application  is  not  using  icons,  create  a 
 dummy  icon  table  with  one  icon  (see  below). 


Nolcons  Install  a  dummy  icon  table.  For  use  in  applications  that 

aren't  using  icons.  Call  early  in  the  initialization  of  the 
application,  before  returning  to  MainLoop. 

Nolcons: 

LoadW    rO,#DummyIconTable       /point  to  dummy  icon  table 
jmp       Dolcons  /install.  Let  Dolcons  rts 

DummylconTabie : 

.byte    1  ;one  icon 

.word    $0000  /dummy  mouse  x  (don't  reposition) 

•byte     $00  /dummy  mouse  y 

.word    $0000  /bitmap  pointer  to  $0000  (disabled) 

.byte     $00  /dummy  x-pos 
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.byte     $00  /dummy  y-pos 

.byte     1,1  /dummy  width  and  height 

.word     $0000  /dummy  event  handler 

MainLoop  and  Icon  Event  Handlers 

When  the  user  clicks  the  mouse  button  on  an  active  icon,  GEOS  MainLoop  will  recognize  this  as 
an  icon  event  and  call  the  icon  event  handler  associated  with  the  particular  icon.  The  icon  event 
handler  is  given  control  with  the  number  of  the  icon  in  rOL  (the  icon  number  is  based  on  the 
icon^s  position  in  the  table:  the  first  icon  is  icon  0).  Before  the  event  handler  is  called,  though, 
MainLoop  might  flash  or  invert  the  icon  depending  on  which  of  the  following  values  is  in 
iconSelFlag: 


Constants  for  iconSelFlag: 


ST  NOTHING 

The  icon  event  handler  is  immediately  called;  the  icon  image  is  untouched. 

ST.FLASH 

The  icon  ijs  inverted  for  selectionFlash  vblanks  and  then  reverted  to  its 
nonnal  state  before  the  event  handler  is  called. 

ST_INVERT 

The  icon  is  inverted  (foreground  screen  image  only)  before  the  event  handler  is 
called.  The  event  handler  will  usually  want  to  revert  the  image  before  returning 
to  MainLoop  by  calculating  the  bounding  rectangle  of  the  icon,  loading 
dispBufferOn  with  ST^WILJFORE,  and  calling  InvertRectangle. 

Detecting  Single-  and  Double-clicks  on  Icons 

When  the  user  first  clicks  on  an  icon,  GEOS  loads  the  global  variable  dblCIickCount  with  the 
GEOS  constant  CLICK^GOUNT,  GEOS  then  calls  the  icon  event  handler  with  rOH  set  to 
FALSE,  indicating  a  single-click.  dblClickCount  is  decremented  at  interrupt  level  every  vblank. 
If  the  icon  event  handler  returns  to  MainLoop  and  the  the  user  again  clicks  on  the  icon  before 
dblClickCount  reaches  zero,  GEOS  calls  the  icon  event  handler  a  second  time  with  rOH  set  to 
TRUE  to  indicate  a  double-click. 

Checking  for  a  double-click  or  a  single-click  (but  not  both)  on  a  particular  icon  is  trivial:  merely 
check  rOH.  If  rOH  is  TRUE  when  you're  looking  for  a  single-click  or  its  FALSE  when  you're 
looking  for  a  double-click,  then  return  to  MainLoop  immediately.  Otherwise,  process  the  click 
appropriately.  This  way,  tS  the  user  single-clicks  on  an  icon  which  requires  double-clicking  or 
double-clicks  on  an  icon  which  requires  single-clicking,  the  event  will  be  ignored 

However,  checking  for  both  a  double-  or  a  single-click  on  the  same  icon  (and  performing  different 
actions)  is  a  bit  more  complicated  because  of  the  way  double-clicks  are  processed:  during  the  brief 
interval  between  the  first  and  second  clicks  of  a  double-click,  the  icon  event  handler  will  be  called 
with  rOH  set  to  FALSE,  which  will  appear  as  a  single-click;  when  the  second  press  happens 
before  dblClickCount  hits  zero,  the  icon  event  handler  is  called  a  second  time  with  rOH  set  to 
TRUE,  which  will  appear  as  a  double-click.  There  is  no  simple  way  (using  the  GEOS  double- 
click facility)  to  distinguish  a  single-click  which  is  part  of  a  double-click  from  a  single-click  which 
stands  alone 

There  are  two  reliable  ways  to  handle  single-  and  double-click  actions  on  icons:  the  additive 
function  method  and  the  polled  mouse  method.  The  additive  function  method  relies  on  a  simple 
single-click  event  which  toggles  some  state  in  the  application  and  a  double-click  event  (usually 
more  complicated)  which  happens  in  addition  to  the  single-click  event.  The  GEOS  dcskTop  uses 
tiie  additive  function  method  for  selecting  (inverting)  file  icons  on  a  single-click  and  selecting  and 
opening  them  on  a  double-click.  The  icon  event  handler  first  checks  the  state  of  rOH.  If  it  is 
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FALSE  (single-click)  then  the  icon  (and  an  associated  selection  flag)  is  inverted.  If  it  is  TRUE 
(double-click)  then  the  file  is  opened.  If  the  user  single-clicks,  the  icon  is  merely  inverted.  If  the 
user  double-clicks,  the  icon  is  inverted  (on  the  first  click)  and  then  processed  as  opened  (on  the 
second  click). 

Example: 

Icon  double-click  handler 
additive  function  method 

**«★*★********★******★*★★**★★★★*★**★*★*«★***★**★★*★★* 

IconEventl: 

Ida        rOH  ; check  double-click  flag 

bne        10$  /branch  if  second  click  of  a  double-click 

;else,  this  is  a  single-click  or  the 
; first:  push  of  a  double-click, 
;  ;so  just  invert  the  selection 

;and  exit. 


10$: 


90$: 


jsr  Invertlcon 
bra  90$ 

jsr        Open Icon 


rts 


/double-click  detected,  go  process  it 
;fall  through  to  exit 

/return  to  MainLoop 


The  polled-mouse  method  can  be  used  when  the  single-click  and  double-click  functions  are 
mutually  exclusive.  When  a  single-click  is  detected  the  icon  event  handler,  rather  than  returning  to 
MainLoop  and  letting  GEOS  manage  the  double-click,  handles  it  manually  by  loading 
dblCIickCount  with  a  delay  and  watching  mouseData  for  a  release  followed  by  a  second  click. 

Example:  * 

***********************************************  ****:«r«««************** 

Icon  double-click  handler  . 
polled  mouse  method 

**  it**  *ic  **********  it  It-it  itir*  it  *it*it*****ik*irit***icitii*ic* 

IconEvent2 : 

;User  pressed  mouse  once,  start  double-click  counter  going 
LoadB    dblClickCount,#CLICK_COUNT      /start  delay 

/Loop  until  double-click  counter  times-out  or  button  is  released 
10$: 

Ida        dblClickCount  /check  double-click  timer 

beq        30$  /If  timed-out,  no  double-click 

Ida        mouseData  /Else,  check  for  release 

bpl        10$  /loop  until  released 


/mouse  was  released, loop  until  double-click  counter  times-out  or 

/button  is  pressed  a  second  time. 

20$: 

Ida        dblClickCount    /check  double-click  timer 
beq        30$  /If  timed-out,  no  double-click 

Ida        mouseData  ./Else,  check  for  second  press 

bmi        20$  /loop  iinril  pressed 

/.Double-click  detected  (no  single-click) 

.'30$i-      jsr        DoDoubleClick  /do  double-click  stuff 

• bra        90$  /exit 


/Single-click  detected  (no  double-click) 
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jsr        DoSingleClick  ;do  single-click  stuff 

;and  fall  through  to  exit 

/Exit 

90$:      rts  /return  to  MainLoop  - 


Note:  These  techniques  for  handling  single-  and  double-clicks  are  described  here  as  they 
pertain  to  icons;  they  are  not  directly  applicable  to  applications  that  detect  mouse  clicks 
through  otherPressVector.  When  control  vectors  through  otherPressVector,  the 
value  in  rOH  is  meaningless.  For  more  information  on  otherPressVector,  refer  to 

 "Other  Mouse  Presses"  in  this  chapter.  


Other  Things  to  Know  About  Icons 

Icon  Releases  and  otherPressVector 

When  the  user  clicks  on  an  active  icon,  MainLoop  will  call  the  proper  icon  event  routine  rather 
than  vectoring  through  otherPressVector.  However,  the  routine  pointed  to  by 
OtherPressVector  will  get  called  when  the  mouse  is  released.  Applications  that  aren*t  using 
OtherPressVector  can  disable  this  vectoring  by  storing  a.  $0000  into  otherPressVector 
($0000  is  actually  its  default  value).  Applications  that  depend  on  otherPressVector,  however, 
can  check  mouseData  and  ignore  all  releases. 

Example: 

/OtherPressVector  routine  that  ignores  releases  (high  bit  of  mouseData  is  set  on  releases) 

MyOtherPress:  /control  comes  here  from  otherPressVector 

Ida  mouseData  /check  state  of  the  mouse  button 

bmi  90$  /ignore  it  if  it's  a  release 

jsr  PressDown  /otherwise  process  the  press' 

90$: 

rts  /return  to  MainLoop 

For  more  information  on  otherPressVector,  refer  to  "Other  Mouse  Presses"  in  this  chapter. 
Icon  Precedence 

GEOS  draws  icons  sequentially.  Therefore,  if  icons  overlap,  the  ones  which  are  drawn  later  will 
be  drawn  on  top.  When  the  user  clicks  somewhere  on  the  screen,  GEOS  scans  the  icon  table  in  this 
same  order,  looking  for  an  icon  whose  rectangular  boundaries  enclose  the  coordinates  of  the 
mouse  pointer.  If  more  than  one  icon  occupies  the  coordinate  position,  the  icon  that  is  defined  first 
in  the  icon  table  (and  therefore  drawn  on  bottom)  will  be  given  the  icon  event.  If  an  active  menu 
and  an  icon  overlap,  the  menu  will  always  be  given  precedence. 

Disabling  Icons 

An  application  can  disable  an  icon  in  the  current  icon  structure  by  clearing  the  OFF_PIC  ICON 
word  of  tiie  icon  (setting  it  to  $(X)00).  If  an  icon  is  disabled  prior  to  a  call  to  Dolcons,  the  icon 
will  not  be  drawn.  If  an  icon  is  disabled  after  the  call  to  Dolcons,  the  icon  will  remain  on  die 
screen  but  will  be  ignored  during  the  icon  scan.  The  application  can  reenable  the  icon  by  restoring 
the  OFF_PIC^ICON  word  to  its  original  value.  (Actually,  any  non-zero  value  will  do  because 
reenabling  an  Icon  does  not  redraw  it,  it  only  restores  the  coordinates  to  MainLoop's  active 
search  list.) 
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GEOS  128  Icon  Doubling 

as  with  bitmaps,  special  flags  in  the  icon  data  structure  can  be  set  to  automatically  double  the  x- 
position  and/or  icon  width  when  GEOS  128  is  running  in  80-column  mode.  To  have  an  an  icon's 
x-position  automatically  doubled  in  80-column  mode,  bitwise-or  the  OFF_I  X  parameter  with 
DOUBLE^B.  To  double  an  icon*s  width  in  80-colunin  mode,  bitwise-or  the^OFFJ^WIDTH 
parameter  with  DOUBLE_B.  These  bits  will  be  ignormed  when  GEOS  128  is  running  in  40- 
column  mode.  Do  not,  however,  use  these  doubling  bits  when  running  under  GEOS  64.  GEOS  64 
will  try  to  treat  the  doubling  bit  as  part  of  the  coordinate  or  width  value  rather  than  a  special-case 
flag.  For  more  information,  refer  to  "GEOS  128  X-position  and  Bitmap  Doubling"  in  Chapter 
@GR@. 

Example: 

/SAMPLE  GEOS  128  ICON  TABLE  THAT  USES  AUTOMATIC  DOUBLING  FEATURE 
.if  !C128 

.echo     Error:  cannot  assemble  GEOS  128  specific  code  without  C128  flag  set 

.else 

Paintlcon: 


PAINTW  =  PicW 
PAINTH  •=  PicH 
PAINTX  »  16/8 
PAINTY  «  80 

;The  actual  icon  data  structure  to  pass  to  Dolcons  follows 
IconTable: 


I_header : 

.byte  NUMOFICONS 

.word  ((PAINTX*8)   +  (PAINTW*8/2) )    I  DOUBLE^W) 

.byte  PAINTY  +  PAINTH/2 


number  of  icon  entries 
position  mouse  over  paint  icon 


I__entries: 
PaintlStruct : 

.word  Paintlcon 

.byte  (PAINTX  I  DOUBLE_B) 

.byte  PAINTY 

.byte  (PAINTW  |  DOUBLE_B) 

.byte  PAINTH 

.word  PaintEvent 


/pointer  to  bitmap 

;x  card  position  (dbl  in  80-column  mode) 
;y-position 

;icon  width  (dbl  in  80-column  mode) 
;icon  height 
/event  handler 


NUMOFICONS 


(*-I_entries)/IESIZE 


/number  of  icons  in  table 


/Dummy  icon  event  routines  which  do  nothing  but  return 
PaintEvent: 
rts 


.endif 
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Apple  GEOS  Double-width  and  Aux-memory  Icons 

As  with  Apple  GEOS  bitmaps,  special  flags  can  be  set  in  the  icon  data  structure  to  double  an  icon's 
width  and/or  lcx)k  for  the  icon  image  data  in  auxiliary  memory.  To  double  an  icon's  width,  bitwise- 
or  the  OFF_I_^WIDTH  parameter  with  DOUBLE  B.  To  mark  the  OFF  I  PIC  word  as  an 
address  in  auxiliary  memory,  bitwise-or  the  OFF_r_X  parameter  with  INaTIX_B.  For  more 
information,  refer  to  "Apple  Bitmap  Doubling  and  Aux^emory  Bitmaps"  in  Chapter  @GR@. 

Menus 

Menus,  one  of  the  most  common  and  powerful  user-interface  facilities  provided  by  GEOS,  allow 
the  application  to  offer  lists  of  items  and  options  to  the  user.  The  familiar  menus  of  the  GEOS 
deskTop,  for  example,  provide  options  for  selecting  desk  accessories,  manipulating  files,  copying 
disks,  and  opening  applications.  Virtually  every  GEOS-based  program  will  take  advantage  of  these 
capabilities,  providing  a  consistent  interface  across  applications. 

GEOS  menus  come  in  two  flavors:  horizontal  and  vertical.  The  main  menu,  the  menu  which  is 
always  displayed,  is  usually  of  the  horizontal  type  and  is  typically  placed  at  the  top  of  the  screen. 
Each  selection  in  the  main  menu  usually  has  a  corresponding  vertical  sub-menu  that  opens  up  when 
an  item  in  the  main  menu  is  chosen.  These  sub-menus  can  contain  items  that  trigger  the  application 
to  perform  some  action.  They  can  also  lead  to  further  levels  of  sub-menus.  For  example,  a 
horizontal  main  menu  item  can  open  up  to  a  vertical  menu,  which  can  have  items  which  then  open 
up  other  horizontal  sub-menus,  which  can  then  lead  to  other  vertical  menus,  and  so  on. 

Division  of  Labor  with  Menus 


GEOS  divides  the  labor  of  handling  menus  between  itself  and  the  application.  The  GEOS  Kemal 
handles  all  of  the  user's  interaction  with  the  menus.  This  includes  drawing  the  menu  items, 
opening  up  necessary  sub-menus,  and  restoring  the  Screen  area  from  the  background  buffer  when 
the  menus  are  retracted.  MainLoop  manages  the  menus,  keeping  track  of  which  items  the  user 
selects.  If  the  user  moves  off  of  the  menu  area  without  making  a  selection,  GEOS  automatically 
retracts  the  menus  without  alerting  the  application. 

If  the  user  selects  a  menu  item  which  generates  a  menu  event,  the  application's  menu  event  handler 
is  called  with  the  menus  left  open.  Leaving  the  menus  open  allows  the  application  to  choose  when 
and  how  to  retract  them:  all  the  way  back  to  the  main  menu,  up  one  or  more  levels  (for  multiple 
sub-menus),  or  up  no  levels  (keeping  the  current  menu  open).  This  lets  the  application  choose  the 
menu  level  which  is  given  control  upon  return,  thereby  allowing  multiple  selections  from  a  sub- 
menu without  forcing  the  user  to  repeatedly  traverse  the  full  menu  tree  for  each  option. 

Menu  Data  Structure 

The  main  menu,  all  its  sub-menus,  their  individual  selectable  items,  and  various  attributes 
associated  with  each  menu  and  each  item  are  all  stored  in  a  hierarchical  data  structure  called  the 
menu  tree.  Conceptually,  a  menu  tree  with  multiple  sub-menus  might  have  the  following  layout: 


9 


icons,  Menus,  and  Other  Mouse  Presses 


sub-menu 


Level  0 


gill  Level  1 


Level  2 
Level  3 


Sample  Menu  Tree 


The  main  menu  (or  level  0)  is  the  first  element  in  the  tree;  it  is  the  menu  that  is  always  displayed 
while  menus  are  enabled.  Each  item  in  a  main  menu  will  usually  point  to  a  secondary  menu  or 
submenu.  Items  in  these  submenus  can  point  to  events  (alerts  to  Ae  application  that  an  item  was 
selected)  or  they  can  point  to  additional  submenus.  Menus  are  linked  together  by  address  pointers. 

Sub-menus  are  sometimes  referred  to  as  child  menus,  and  the  menu  which  spawned  the  sub-menu 
as  its  parent.  Sub-menus  can  be  nested  to  a  depth  determined  by  the  GEOS  constant 
MAX_M  NESTEVG,  which  reflects  the  internal  variable  space  allocated  to  menus.  The  depth  or 
level  of  tEe  current  menu  can  be  determined  by  the  GEOS  variable  menuNumber,  which  can 
range  from  0  to  (MAX^M^NESTING- 1). 

In  memory,  all  menus,  whether  the  main  menu  or  its  children,  are  stored  in  the  same  basic  menu 
structure  format  Each  menu  is  comprised  of  a  single  menu  header  block  followed  by  a  number  of 
menu  item  blocks  (one  for  each  selectable  item  in  the  menu): 
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menu 


Menu/Sub-menu  structure 


Menu/Sub-menu  Header 

The  menu  header  is  a  seven-byte  structure  that  specifies  the  size  and  location  of  the  menu  (How  big 
is  the  rectangle  that  suirounds  the  menu  and  where  should  the  menu  be  drawn?),  any  attributes  that 
affect  the  entire  menu  (Is  it  a  vertical  or  horizontal  menu?),  and  the  number  of  selectable  items  in 
the  menu.  The  header  is  in  the  following  format: 

Menu/Sub-menu  Table  Header: 


Index 

Constant 

Size 

Description 

+0 

OFF   M  Y  TOP 

byte 

Top  edge  of  menu  rectangle  (yl  pixel  position). 

+1 

OFF  M  Y  BOT 

byte 

Bottom  edge  of  menu  rectangle  (yl  pixel  position). 

+2 

OFF  M  X  LEFT 

wad 

Left  edge  of  menu  rectangle  (xl  pixel  position). 

+4 

OFF_M_X_RIGHT 

wcxd 

Right  edge  of  menu  rectangle  (x2  pixel  position). 

+6 

OFF^NUM^M.ITEMS 

byte 

Menu  type  bitwise-or*ed  with  number  of  items  in  this 
menu/sub-menu. 

The  first  six  bytes  specify  the  screen  location  and  size  of  the  menu  with  the  positions  of  the 
bounding  rectangle  in  pixel  positions.  The  x-positions  are  word  (two-byte)  vdues  and  the  y- 
positions  are  byte  values  These  values  are  absolute  screen  pixel  positions.  The  size  of  die  bounding 
rectangle  depends  on  the  number  of  menu  items  and  the  size  of  text  strings  within  the  toenu.  The 
height  of  the  rectangle  can  be  calculated  with  the  constant  M^HEIGHT:  a  horizontal  menu  is 
always  a  height  of  M  HEIGHT,  and  a  vertical  menu  is  a  height  of  the  number  of  menu  items 
multiplied  by  M  HEIGHT.  For  example,  the  height  of  a  vertical  menu  with  seven  items  would 
be  7*M_HEIGITT.  The  width  of  a  menu  is  more  difficult  to  calculate  because  it  depends  on  the 
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length  of  the  individual  text  strings.  It  is  best  to  use  a  large  number  for  this  dimension  and  adjust  it 
to  a  smaller  size  if  necessary. 


Important:  GEOS  64  and  GEOS  128  before  version  2.0  do  not  correctly  handle  menus  that 
 extend  beyond  an  x-position  of  255.  This  problem  does  not  exist  in  Apple  GEOS. 

All  menus  and  sub-menus  are  positioned  independently.  This  means  that  the  main  menu  need  not 
be  at  the  top  of  the  screen  (it  can  be  inside  a  window,  for  example),  and  sub-menus  need  not  be 
adjacent  to  their  parent  menus  (although  that  is  where  you  will  usually  want  them).  You  can 
experiment  with  the  flexibility  of  menu  positioning  to  customize  your  applications. 

The  seventh  byte  is  the  attribute  byte.  It  is  the  number  of  selectable  items  in  the  menu  bitwise-or'ed 
with  any  menu  type  flags.  A  menu  can  have  as  many  as  MAX_M_ITEMS  selectable  menu 
items. 


Menu/Sub-menu  Types  (use  in  attribute  byte): 


Constant 

Description 

HORIZONTAL 

Arrange  menu  items  in  this  menu/sub-menu  horizontally. 

VERTICAL 

Arrange  menu  items  in  this  menu/sub-menu  vertically. 

CONSTRAINED 

Constrain  the  mouse  to  the  menu/sub-menu.  If  the  menu  is  a  sub-menu,  the 
mouse  can  still  be  moved  off  to  the  parent  menu  (off  the  top  of  a  vertical  sub- 
menu or  off  the  left  of  a  horizontal  menu). 

UN.CONSTRAINED 

Do  not  constrain  the  mouse  to  the  menu/sub-menu.  If  the  user  moves  off  of 
the  menu,  GEOS  will  retract  it 

Bitwise  Breakdown  of  the  Attribute  Byte: 

7        6        5  4 

3       2       1  0 

b7    b6  1 

b5-bO  1 

b7  orientation:  1=  vertical;  0  =  horizontal, 

b6  constrained:  1  =  yes;  0  =  no. 

b5-bO      number  of  items  in  menu/sub-menu  (up  to  MAX_M_ITEMS). 


Some  of  the  menu  types  are  obviously  mutually  exclusive:  you  can't,  for  example,  make  a  menu 
both  vertical  and  horizontal,  nor  simultaneously  constrained  and  unconstrained. 

A  vertical,  unconstrained  menu  with  seven  selectable  items  would  have  an  attribute  byte  of: 

.byte     (7   |  VERTICAL  |  UN_CONSTRAINED) 

A  horizontal,  constrained  menu  with  1 1  selectable  items  would  have  an  attribute  byte  of: 

.byte     (11   I  HORIZONTAL  I  CONSTRAINED) 

Most  sub-menus  are  unconstrained:  if  the  user  moves  the  pointer  off  the  sub-menu,  all  opened 
menus  are  retracted  as  if  GotoFirstMenu  had  been  called.  A  constrained  menu,  on  the  other 
hand,  restricts  the  pointer  from  moving  off  the  menu  area  from  aU  but  one  side.  A  constrained 
menu  will  only  allow  the  pointer  to  move  off  the  side  leading  back  to  where  it  expects  the  parent 
menu  to  be:  off  the  top  for  a  vertical  sub-menu  and  off  the  left  for  a  horizontal  sub-menu.  If  the 
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user  moves  off  of  a  constrained  menu  (in  the  only  available  direction),  the  current  sub-menu  is 
retracted  and  the  parent  menu  becomes  active  as  if  DoPreviousMenu  had  been  called. 

NOTE:    The  constrain  option  is  only  applicable  to  sub-menus  —  if  the  CONSTRAINED  flag 
is  set  in  the  main  menu  (level  0),  the  option  will  have  no  effect. 


Menu  Item  Structure 

For  each  selectable  item  in  a  menu  (the  number  items  is  specified  in  the  header)  there  is  a  five-byte 
item  structure.  These  item  structures  follow  the  menu  header  in  memory.  The  first  item  represents 
the  first  menu  selection  (top-  or  leftmost),  the  second,  the  second,  and  so  on.  Each  item  structure 
specifies  the  text  that  will  appear  in  the  menu,  what  happens  when  the  item  is  selected  (Will  it 
generate  an  event  or  a  sub-menu?),  and  the  appropriate  event  routine  or  sub-menu.  Each  menu  item 
is  in  the  following  format: 

Menu  Item: 


Index 

Constant 

Size 

Description 

+0 

OFF_TEXTJTEM 

Pointer  to  null-terminated  text  string  for  this  menu 
item. 

+2 

OFF  TYPE  ITEM 

byte 

Selection  type  (sub-menu,  event,  dynamic  sub-menu). 

+3 

OFF_POINTERJTEM 

woid 

Pointer  to  sub-menu  data  structure,  event  routine,  or 
dynamic  sub-menu  routine,  depending  on  selection  type. 

The  first  word  of  the  item  is  a  pointer  to  the  text  that  will  be  placed  in  the  menu.  The  text  is 
expected  to  be  null-terminated  (the  last  byte  should  be  $00  or  NULL).  If  the  menu  rectangle 
specified  in  the  header  is  not  wide  enough  to  contain  the  entire  text  string,  the  text  will  be  clipped  at 
the  right  edge  when  the  menu  is  drawn. 

The  byte  following  the  text  pointer  (die  third  byte)  is  an  item  type  indicator.  Each  selectable  item 
can  either  be  an  an  action,  a  sub-menu,  or  a  dynamic  sub-menu  selection.  An  action  "type  item 
generates  a  menu  event  from  MainLoop.  A  sub-menu  type  item  automatically  opens  up  a  sub- 
menu structure.  And  a  dynamic  sub-menu  type  selection  opens  up  a  sub-menu,  but  before  it  does, 
it  calls  an  application's  routine.  Dynamic  sub-menus  are  useful  for  modifying  a  menu  structure  on 
the  fly.  For  example,  a  point  size  sub-menu,  such  as  those  used  in  geoWritc,  can  be  changed 
dynamically  when  a  new  font  is  selected.  When  the  user  chooses  the  font  item,  the  dynamic  sub- 
menu routine  checks  the  list  of  available  point  sizes  and  builds  out  the  point  size  sub-menu  based 
on  its  findings.  The  following  table  summarizes  the  three  menu  item  types: 

Types  of  Menu  Items  (for  use  in  item  type  byte): 


Constant  Description 


SUB.MENU 

This  menu  item  leads  to  a  sub-menu.  The  OFF_POINTER_ITEM  is  a 
pointer  to  the  sub-menu  data  structure  (points  thelfirst  byte  of  a  menu/sub- 
menu header). 

DYN.SUB.MENU 

This  menu  item  is  a  dynamic  sub-menu.  The  OFF_POINTER_ITEM  is  a 
pointer  to  a  dynamic  sub-menu  routine  that  is  called  before  the  menu  is 
actually  drawn.  The  dynamic  sub-menu  routine  can  do  any  necessary  pre- 
processing and  return  with  rO  containing  a  pointer  to  a  sub-menu  data 
structure  or  $0000  to  ignore  the  selection. 

MENU.ACnON 

This  menu  item  generates  an  event.  The  OFF^POINTERJTEM  is  a 
pointer  to  the  event  routine  that  will  to  call. 
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Bitwise  Bre^     mn  of  the  Item  Type  Byte: 

7        6  4        3        2        1  0 

I  b7  I  b6  I  d:  I  b4-b0  1 

b7  sub-menu  flag. 

b6  dynamic  sub-menu  flag. 

b4-b0      reserved  for  future  use. 


Example  Menu 

The  following  code  fragment  defines  an  unconstrained  horizontal  menu  of  three  items,  suitable  for 
use  as  the  main  menu.  Each  item  in  the  menu  points  to  a  sub-menu  that  is  not  shown 
(GeosMenu,  FileMenu,  and  EditMenu). 

Example: 


/SAMPLE  MENU  TABLE 


MENU  CONSTANTS  *** 
/bounding  rectangle 

MAINXl  =  0  /left 

MAINYl  =  0  /top  edge 

MAINX2  =  72  /right 

MAINY2  =  MAINYl  +  M  HEIGHT  /bottom  edge 


/•• 

/***  MENU  DEFINITION  *** 
•  ************************ 


HEADER 
MainMenu : 

.byte  MAINYl 

.byte  MAINY2 

.word  MAINXl 

.word  MAINX2 


/top 
/bottom 
/  left 
/right 


.byte     (  HORIZONTAL  I  UN_CONSTRAINED  I  M_ITEMS) 


/***  ITEMS 
Mainltems: 
/Geos 


.word 
.byte 
.word 


GeosText 
SUB_MENU 
GeosMenu 


/pointer  to  null-terminated  text 

/generates  sub-menu 

/pointer  to  sub-menu  structure 


/File 


.word 
.byte 
.word 


FileText 
SUB_MENU 
FileMenu 


/pointer  to  null-terminated  text 

/generates  sub-menu 

/pointer  to  sub-menu  structure 


/Edit 


•  word 
.byte 
.word 


EditText 
SDB_MENU 
EditMenu 


/pointer  to  null-terminated  text 

/generates  sub-menu 

/pointer  to  sub-menu  structure 


M  ITEMS 


(*  -  Mainltems) /MISI2E         /number  of  items  in  the  menu 


/text  string  for  Geos  selection 
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GeosText : 


.byte 

Geos  t 

NULL 

;text  string 

for  File 

selection 

FileText : 

•  byte 

"File", 

NULL 

;text  string 

for  Edit 

selection 

Edit Text : 

.byte 

"Edit", 

NULL 

; null-terminated  item  string 


; null-terminated  item  string 


/null-terminated  item  string 


Installing  Menus 


When  an  application  is  first  loaded,  GEOS  will  not  have  an  active  menu  structure.  GEOS  must  be 
given  the  address  of  the  application's  menu  structure  before  MainLoop  can  display  and  track  the 
user's  interaction  with  it  GEOS  provides  one  routine  for  installing  menus: 


!•  DoMenu 


Display  and  activate  a  menu  structure. 


] 


DoMenu  draws  the  main  menu  on  the  foreground  screen  and  instructs  MainLoop  to  begin  taking 
care  of  all  menu  processing.  The  menu  stays  activated  and  enabled  until  the  MENU_ON_BIT  or 
the  MOUSE_ON  BIT  of  mouseOn  is  cleared  or  another  menu  is  installed  by  calling  iJbMenu 
with  the  address  o7a  different  menu  structure.  In  either  case,  the  old  menu  is  not  erased  from  the 
foreground  screen  by  GEOS.  The  application  must  recover  the  area  from  the  background  buffer 
itself. 


MainLoop  and  Menu  Events 

When  the  user  clicks  the  mouse  button  on  a  menu  item,  GEOS  MainLoop  will  invert  the  selection 
and  examine' the  item  data  block,  processing  the  selection  according  to  its  type. 

SUB^MENU 

If  the  menu  item  is  of  the  SUB^MENU  type,  then  menuNumber  is  incremented,  the 
appropriate  sub-menu  is  drawn,  anS  MainLoop  begins  tracking  the  user's  interaction  with  the 
sub-menu,  making  it  the  current  menu.  If  the  user  moves  off  of  a  sub-menu  back  onto  its  parent 
menu,  MainLoop  will  retract  the  sub-menu,  decrement  menuNumber,  and  make  the  parent 
menu  the  current  menu.  If  the  user  moves  off  of  the  menus  entirely  (assuming  this  is  possible  — 
the  menu  might  be  constrained),  then  MainLoop  retracts  all  sub-menus  back  up  to  the  the  main 
menu  and  sets  menuNumber  to  zero. 

DYNAMIC  SUB  MENU 

If  the  menu  item  is  of  the  DYNAMIC_SUB^MENU  type,  MainLoop  calls  the  routine  whose 
address  is  in  tiie  item  structure.  This  routine  Ts  called  before  the  sub-menu  is  drawn  and  before 
menuNumber  is  incremented.  The  accumulator  will  contain  the  item  number  selected  (item 
numbers  start  with  zero).  When  the  routine  returns  with  the  address  of  the  appropriate  sub-menu  in 
rO,  MainLoop  continues  processing  as  if  it  was  handling  a  SUB_MENU  type  menu.  If  the 
dynamic  sub-menu  routine  returns  $0000  in  rO,  then  the  sub-menu  i^not  opened  and  the  current 
menu  remains  active. 
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MENU^CTION 

If  the  menu  item  is  of  the  MENU  ACTION  type,  GEOS  flashes  the  menu  inverted  for 
selectionFIash  vblanks.  selectionPlash  is  a  GEOS  variable  which  is  initialized  with  the 
constant  SELECTION_DELAY,  but  may  be  adjusted  by  the  application.  MainLoop  will  then 
call  the  menu  event  routine  whose  address  is  in  the  item  structure,  passing  the  number  of  the 
selected  item  in  the  accumulator  (item  numbers  start  with  zero).  One  of  the  first  things  a  menu 
event  routine  must  do,  among  its  own  duties,  is  specify  which  menu  level  MainLoop  should 
return  to  when  it  gets  control.  This  is  done  by  calling  one  of  the  GEOS  routines  designed  for  this 
purpose: 


•  ReDoMenu 

Reactivate  the  menu  at  the  current  level. 

•  DoPreviousMenu 

Retract  the  current  sub-menu  and  reactivate  the  menu  at  the 
previous  level. 

•  GotoFirstMenu 

Retract  all  sub-menus  and  reactivate  the  menu  at  the  main  menu 
level. 

These  routines  retract  menus  as  necessary  (recovering  from  the  background  buffer)  and  sets  special 
flags  which  tell  MainLoop  what  has  happened;  MainLoop  is  not  given  control  at  this  time  — 
that  is  the  job  of  the  menu  event  handler's  rts.  If  an  application's  menu  event  handler  does  not  call 
one  of  these  routines  before  it  returns  to  MainLoop,  the  menu  will  remain  open  but  inactive. 


NOTE:  A  menu  remains  on  the  foreground  screen  until  DoPreviousMenu  or 
GotoFirstMenu  is  called  to  retract  it.  If  graphics  need  to  be  drawn  in  the  area 
obscured  by  a  menu,  but  menus  cannot  be  retracted,  then  limit  drawing  to  th; 

 background  buffer  by  setting  the  proper  bits  in  dispBufferOn.  j 


Specialized  Menu  Recover  Routines 

• 

GEOS  provides  two  very  low-level  menu  routines  which  recover  areas  obscured  by  menus  from 
the  background  buffer.  Usually  these  routines  are  only  called  internally  by  the  higher-level  menu 
routines  such  as  DoPreviousMenu.  They  are  of  little  use  in  most  applications  and  are  included  in 
the  jump  table  mainly  for  historical  reasons.  There  are  two  routines: 

•  RecoverMenu        Recovers  the  current  menu  from  the  background  buffer  toThe 

  foreground  screen.  

•  RecoverAllMenus  Recovers  all  extant  menus  and  sub-menus  from  the  background 

buffer  to  the  foreground  screen. 

Advanced  Menu  Ideas 

Menu  routines  can  be  as  clever  as  desired  One  common  technique  involves  dynamically  modifying 
the  text  strings  associated  with  menu  items.  This  can  be  used,  for  example,  to  add  asterisks  next  to 
currendy  active  options  as  they  are  selected 
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Menus  and  Mouse-Fault  Interaction 


How  GEOS  uses  Mouse  Faults 

In  general,  the  following  is  true: 

•  When  a  menu  is  down,  the  system  interrupt-level  mouse-processing  routine  is  checking 
for  two  types  of  mouse  faults:  the  mouse  moving  outside  of  the  rectangle  defined  by 
mouseTop,  mouseBottom,  mouseLeft,  and  mouseRight  and  the  mouse  moving  off 
of  the  menu.  It  sets  bits  in  mouseFauIt  accordingly. 

•  If  the  menu  is  unconstrained,  mouseTop,  mouseBottom,  mouseLeft,  and 
mouseRight  are  set  to  full-screen  dimensions,  thereby  ruling  out  this  type  of  mouse  fault, 

•  If  the  menu  is  constrained,  mouseTop,  mouseBottom,  mouseLeft,  and 
mouseRight  are  set  to  the  dimensions  of  the  current  menu's  rectangle.  This  will  keep  the 
mouse  from  moving  off  of  the  menu  area  (and  will  also  generate  a  mouse  fault  when  an 
edge  is  encountered). 

•  The  system  mouse  fault  routine  (called  through  mouseFauItVec)  checks  the 
mouseFauIt  variable.  If  the  mouse  faulted  by  moving  off  of  the  menu  (only  possible  if 
the  menu  is  unconstrained),  DoPreviousMenu  is  called.  If  the  user  moved  off  of  the 
sub-menu  without  moving  onto  another  menu,  mouse  menu  faults  will  continue  to  retract 
menus  until  only  the  main  menu  is  displayed.  If  the  mouse  faulted  by  attempting  to  move 
beyond  the  mouseTop  on  a  vertical  sub-menu  or  mouseLeft  on  a  horizontal  sub-menu 
(only  possible  on  a  constrained  menu)  then  DoPreviousMenu  is  called. 


Application's  Use  of  Mouse  Faults 

When  the  user  is  interacting  with  menus,  the  system  uses  the  mouse  fault  variables  (mouseTop, 
mouseBottom,  mouseLeft,  and  mouseRight)  and  expects  its  own  fault  service  routine  to  be 
called  through  mouseFauItVec.  If  an  application  needs  use  mouse  faults  for  its  own  purposes, 
should  first  disable  menus  by  clearing  the  MENUON^BIT  of  mouseOn  Before  reenabling 
menus,  it  should  set  the  fault  variables  to  the  full  screen  dimensions  and  call  StartMouseMode  to 
restore  the  system's  fault  service  routine: 


*  ************  ***i«r********#****************4r************ 

; Routine  to  restore  the  mouse  service  routines  to  an 
; operational  state  after  an  application's  use  of 
/mouse  faults  through  mouseFauItVec.  Should  be  called 
/before  menus  are  reenabled. 

Re set Mouse: 


  Following  lines  changed  to  save  bytes 

LoadW  mouseLeft,  #0 

LoadB  mouseTop,  #0 

Ida  #0 

St a  mouseLeft 

sta  mouseLeft+1 

sta  mouseTop 
.if  (C128) 

LoadW  rO,# (SC_40_WIDTH-1 

Idx  #rO 

jsr  NormalizeX 

MoveW  rO, mouseRight 
•  else     ; (APPLE  I  I  C64) 


reset  mouse  left  to  left  screen  edge 
and  mouse  top  to  top  screen  fedge 


I  DOUBLE__W  I  ADD1_W)         /put  in  zp  reg  to  normalize 
/point  to  register 
/double  if  in  80-column 
/mouse  right  to  right  screen  edge 
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LoadW    mouseRight, #SC_PIX_WIDTH-1 


/mouse  right  to  right  screen  edge 


.endif 


LoadB  mouseBottom,  #SC__PIX_HEIGHT-1 
clc 

jsr  StartMouseMode 
rts 


mouse  bottom  to  bottom  screen  edge 
don't  reposition  mouse... 


exit 


Sample  Menu 


Other  Mouse  Presses 

When  the  user  clicks  the  mouse  somewhere  on  the  screen  where  there  is  no  active  menu  or  icon, 
GEOS  consideres  this  an  "other"  press  and  checks  otherPressVector  for  an  application- 
provided  subroutine.  If  otherPressVector  is  $0000,  then  the  press  is  ignored,  if 
OtherPressVector  contains  anything  but  $0000,  GEOS  treats  the  value  as  an  absolute  address 
and  simulates  an  indirect  jsr  to  that  address.  otherPressVector  defaults  to  $0000  at  application 
startup. 

OtherPressVector  gets  called  on  all  presses  that  are  not  on  an  active  icon  or  menu  and  on  all 
releases,  whether  on  a  menu,  icon,  or  anywhere  else.  In  most  cases,  the  application  will  want  to 
ignore  the  releases.  This  is  done  simply  by  checking  mouseData  for  the  current  state  of  the 
mouse  button,  as  in:- 


Because  otherPressVector  gets  called  on  each  press  (and  release),  any  double-click  detection 
must  be  performed  manually  by  the  other-press  routine.  Handling  double-clicks  through 


Ida 
bpl 
rts 


mouseData 
10$ 


; check  state  of  the  mouse  button 

/branch  to  handle  presses 

;but  return  immediately  to  ignore  releases 


10$: 
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otherPress Vector  is  similar  to  the  polled  mouse  method  used  with  icons,  the  major  difference 
being  a  check  for  releases  on  entry. 

Example: 

/Ignore  releases  on  entry 

Ida        mouseData  /check  state  of  the  mouse  button 

bpl        5$  /branch  to  handle  presses 

rts  /but  return  immediately  to  ignore  releases 

5$: 

/User  pressed  mouse  once,  start  double-click  counter  going 
LoadB     dblClickCount,  #CLICK__COUNT      /start  delay 

/Loop  until  double-click  counter  times-out  or  button  is  released 
10$: 

Ida        dblClickCount  /check  double-click  timer 

beq        30$  /If  timed-out,  no  double-click 

Ida        mouseData  /Else,  check  for  release 

bpl        10$  /loop  until  released 

/mouse  was  released, loop  until  double-click  counter  times-out  or 

/button  is  pressed  a  second  time. 

20$: 

Ida        dblClickCount  /check  double-click  timer 

beq        30$  /If  timed-out,  no  double-click 

Ida        mouseData  /Else,  check  for  second  press 

bmi        20$  /loop  until  pressed 

^•.Double-click  detected  (no  single-click) 

-J0.$:       jsr        DoDoubleClick  /do  double-click  stuff 

^'  bra        90$  /exit 

'  /Single-click  detected  (no  double-click) 

— -r-      jsr        DoSingleClick  /do  single-click  stuff 

•  / and ^f all  through  to  exit 

/Exit 

90$:       rts  /return  to  MainLoop 
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Process  Library 


A  process  is  a  is  an  event  that  is  triggered  on  a  regular  basis  by  a  timer.  This  allows  GEOS  to 
generate  an  event  at  specific  time  intervals,  such  as  20  times  per  second,  once  every  minute,  or  five 
times  each  hour.  Processes  allow  a  limited  form  of  multitasking,  where  many  short  routines  can 
appear  to  run  concurrently  with  MainLoop.  Thus  an  application  could  update  an  alarm  clock  and 
scroll  the  work  area  while  calculating  a  cell  in  a  spreadsheet.  Applications  can  also  use  processes  to 
monitor  the  mouse.  geoPaint,  for  example,  uses  a  process  to  monitor  the  mouse's  position  when 
using  the  line  tool;  when  the  mouse  moves,  the  process  prints  the  new  line  length  in  the  status 
window.  geoPublish  operates  in  a  similar  manner,  using  a  process  to  update  the  values  in  the 
coordinate  boxes  as  the  user  moves  the  across  the  preview  page. 


Note:  Processes  do  not  provide  true  multitasking.  There  is  no  interrupt-driven  context 
switching,  nor  any  concurrence  (where  two  routines  run  simultaneously).  Processes 
are  best  thought  of  as  events  triggered  off  of  MainLoop  just  like  any  other  event. 
When  one  process  is  running,  the  next  process  in  line  won't  get  executed  until  the  first 

 finishes  and  returns  to  MainLoop.  


Process  Nomenclature 

There  are  a  number  of  terms  associated  with  processes.  Each  process  has  a  countdown  timer. 
When  the  countdown  timer  reaches  zero  or  times-out,  the  process  becomes  runable.  If  a  process  is 
frozen,  its  timer  is  not  being  decremented.  The  timer  will  continue  when  the  process  is  unfrozen.  If 
a  process  is  blocked,  a  process  event  will  not  be  generated  until  the  process  becomes  unblocked. 


Process  Data  Structure 


The  application  must  initialize  the  GEOS  process  handler  with  a  process  data  structure.  Thfe 
process  data  structure  contains  the  necessary  information  for  all  the  desired  processes.  The  table 
can  specify  up  to  MAX^PROCESSES  (formeriy  MAXIMUM_PROCESSES)  processes. 
Each  process  in  the  table  is  in  the  following  format: 


Index    Constant  Size  Description 


+0 

OEF.PJVENT 

word 

Pointer  to  event  routine  that  is  called  when  this 
process  times-out. 

+2 

OFF^P.TIMER 

word 

Timer  initialization  value:  number  of  vblanks  to 
wait  between  one  event  trigger  and  the  next. 

The  first  word  is  the  address  of  the  process  event  handler.  The  process  event  handler  is  much  like 
any  other  event  handler:  it  is  called  by  MainLoop  when  process  becomes  runable  (as  opposed  to, 
say,  when  the  user  clicks  on  an  icon  or  selects  a  menu  item)  and  is  expected  to  return  with  an  rts. 

The  second  word  is  the  number  of  vblanks  to  wait  between  one  event  trigger  and  the  next.  If  the 
the  OFF_P_TIMER  word  of  a  process  is  set  to  20,  for  example^  then  the  process  event  handler 
will  be  called  every  20  vblanks  (about  3  times  per  second  on  NTSC  machines  and  2.5  times  per 
second  on  PAL  machines). 
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Sample  Process  Table 

The  following  data  block  defines  three  processes,  each  with  a  different  process  event  handler.  The 
first  process  will  execute  once  every  10  vblanks,  the  second  will  execute  once  every  second,  and 
the  third  will  execute  once  every  five  minutes.  Notice  the  use  of  the  FRAME_RATE  constant  to 
calculate  the  correct  vblank  delay  for  PAL  and  NTSC  machines  and  the  automatic  assignment  of 
process  constants  with  (*  -  PrTabIe)/PSIZE. 

Sample  process  data  structure 

oc 

PrTable: 
A*  MOUSE  CHECK  PROCESS*** 

Check  mouse  position  and  change  pointer  form  as 
necessary. 

MOUSECHECK        «  (*-P^Table) /PSIZE  /process  number 

.word    CheckMouse  /process  event  routine 

.word     10  ; check  every  10  vblanks 

;***  REAL-TIME  CLOCK  PROCESS  *** 

;  Increment  a  r^^l-time  clock  counter  every  second 

RTCLOCK  =  (*-P5,Table) /PSIZE  /process  number 

.word    Tick  /process  event  routine 

.word    FRAME_RATE  /one  second  worth  of  vblanks 

***  SCREEN-SAVER  PROCESS  *** 

Save  the  screen  by  turning  off  colors  after  five 
minutes. 

SCRNSAVER          =  (*-Pr^able) /PSIZE  /process  number 

.word    ScreenSave  /process  event  routine 

.word    5*60*FRAME_RATE  /frames  in  5  minutes 

/delay  «  5  min*  60  sec/min  *  frames/sec) 

NUM_PROC  =  (*-ProcTable) /PSIZB*4r         /number  of  processes  in  this  table       A/0  T  tj 

/for  passing  to  InitProcesses 

.if         (NUM__PROC  >  MAX_PROCESSES)  /check  for  too  many  processes 

echo      Warning:  too  many  processes 

.endif 


Process  Management 


Installing  Processes 

The  application  must  install  its  processes  by  telling  GEOS  the  location  of  the  process  data  structure 
and  the  number  of  processes  in  the  structure.  GEOS  provides  one  routine  for  installing  processes: 

pTnitProcesses        Initialize  and  install  processes. 

InitProcesses  copies  the  process  data  structure  into  an  internal  area  of  meir;  -  v,  hidden  from  the 
application.  GEOS  maintains  the  processes  within  this  internal  area,  keepi:  rack  of  the  event 
routine  addresses,  the  timer  initialization  values  (used  to  reload  the  timers  afie:  :  time-out),  the 
current  value  of  the  timer,  and  the  state  of  each  process  (i.e.,  frozen,  blocke  d,  runable).  The 
application's  copy  of  the  process  data  structure  is  no  longer  needed  because  GEOS  remembers  this 
information  until  a  subsequent  call  to  InitProcesses. 
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Example: 

Initialize  process  table  *** 

LoadW     rO,#ProcTable  /point  at  process  data  structure 

Ida        #NUM_PROC  /pass  actual  number  of  processes 

jsr        InitProcesses  /call  GEOS  to  install  processes 

/processes  in  table  are  now  blocked  and  frozen 


Starting  and  Restarting  Processes 

When  a  process  table  is  installed,  the  processes  do  not  begin  executing  immediately  because  all 
processes  are  initialized  as  frozen.  GEOS  provides  a  routine  to  simultaneously  unblock  and 
unfreeze  a  single  process  while  reinitializing  its  countdown  timer: 

plRestartProcess       Initialize  a  process's  timer  value  then  unblock  and  unfreeze  it.  | 

RestartProcess  should  always  be  used  to  start  a  process  for  the  first  time,  otherwise  the  timer 
will  begin  in  an  unknown  state. 

Example: 


start  all  processes  *** 

Idx        #NUM_PR0C-1  /process  numbers  range  from  0  to  NUM_PR0C-1 

10$: 

jsr        RestartProcess  /reset  timer,  unblock,  and  unfreeze  process 

dex  /next  process 

bpl        10$  /loop  until  done 

RestartProcess  can  also  be  used  rewind  a  process  to  the  beginning  of  its  cycle.  One  application 
for  this  is  a  screen-saver  utility  which  blanks  the  screen  after,  say,  five  minutes  of  inactivity  to 
prevent  phosphor  bum-in.  A  five-minute  process  is  established  which,  when  it  triggers  an  event, 
blanks  the  screen.  Any  routine  which  detects  activity  from  the  user  (a  mouse  movement,  button 
press,  keypress,  etc.)  before  the  screen  is  blanked  can  call  RestartProcess  to  reset  the  screen- 
saver  countdown  timer  to  its  initial  five  minute  value. 


Freezing  and  Blocking  Processes 

When  a  process  is  frozen,  its  timer  is  no  longer  decremented  every  vblank.  It  will  therefore  never 
time-out  and  generate  a  process  event  When  a  process  is  unfrozen,  its  timer  again  begins  counting 
from  the  point  where  it  was  frozen.  GEOS  provides  the  following  routines  for  freezing  and 
unfreezing  a  process's  timer: 


•  FreezeProcess 

Freeze  a  process's  countdown  timer  at  its  current  value. 

•  UnfreezeProcess 

Resume  (unfreeze)  a  process's  countdown  timer. 

Example: 


Freeze  all  processes  *** 
php 
sei 

Idx  #NUM_PR0C-1 

10$: 

jsr  FreezeProcess 
dex 

bpl  10$ 
pip 


disable  interrupts  to  synchronize  freezing 

process  numbers  range  from  0  to  NUM_PR0C-1 

/freeze  process 
/next  process 
•loop  until  done 
/restore  interrupt  status 
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A  process  may  also  be  blocked.  Blocking  a  process  temporarily  prevents  the  event  service  routine 
from  being  executed.  It  does  not  stop  the  timer  from  decrementing,  but  when  the  timer  reaches  zero 
and  the  process  bcomes  runable,  the  event  is  not  generated.  When  a  process  is  subsequently 
unblocked,  its  events  will  again  be  generated.  GEOS  provides  the  following  routines  for  blocking 
and  unblocking  processes: 

•  BlockProcess  Block  a  process's  events.  

•  UnblockProcess     Allow  a  process's  events  to  go  through. 

Example: 

Block  mouse-checking  process  *** 

Idx        #MOUSECHECK  /process  number  of  mouse  check 

jsr        BlockProcess  ;block  it 

Unblock  Real-time  clock  process  *** 

Idx        #RTCLOCK  ; process  number  of  real-time  clock 

jsr        UnblockProcess  /unblock  it 

When  a  timer  reaches  zer  (times-out),  its  process  becomes  runable.  An  internal  GEOS  flag  (called 
the  runable  flag)  is  set,  indicating  to  MainLoop  that  an  event  is  pending.  The  timer  is  then 
restarted  with  its  initialize  "'on  value.  MainLoop  will  ignore  the  runable  flag  as  long  as  the  process 
is  blocked.  When  the  prox  iss  is  later  unblocked,  MainLoop  will  see  the  runable  flag,  recognize  it 
as  a  pending  event,  and  ca:l  the  appropriate  service  routine.  However,  multiple  pending  events  are 
ignored:  if  a  blocked  processes  timer  reaches  zero  more  than  once,  only  one  event  will  be  generated 
when  it  is  unblocked. 

Freezing  vs.  Blocking 

The  differences  between  freezing  and  blocking  are  in  many  cases  unimportant  to  the  application. 
However,  a  good  understanding  of  their  subtleties  will  prevent  problems  that  may  arise  if  the 
wrong  method  is  used. 

Normally,  a  process's  timer  is  decremented  every  vblank.  If  a  process  is  frozen,  however,  the 
GEOS  vblank  interrupt  routine  will  ignore  the  associated  timer.  The  timer  value  will  not  change 
and,  hence,  will  never  reach  zero.  The  process  will  never  become  runable.  If  you  think  of  a 
process  as  a  wind-up  alarm  clock,  freezing  is  equivalent  to  disconnecting  the  drive  spring  —  even 
the  second  hand  stops  moving. 

Freezing  a  process  only  guarantees  that  the  process  will  not  subsequently  become  runable.  The 
process  may  in  fact  already  be  marked  as  runable  and  GEOS  is  only  awaiting  the  next  pass  through 
MainLoop  to  generate  an  event.  (A  process  that  is  marked  as  runable  but  not  yet  run  is  said  to  be 
apending  event.) 

If  a  process  is  blocked  (but  not  also  frozen),  GEOS  Interrupt  Level  will  continue  to  decrement  the 
associated  timer.  If  the  timer  reaches  zero,  GEOS  will  reset  the  timer  and  make  the  process 
runable.  But  MainLoop  will  ignore  the  process  and  not  generate  an  event  because  the  process  is 
blocked.  If  the  process  is  later  unblocked,  the  event  will  be  generated  during  the  next  pass  through 
MainLoop.  Using  the  alarm  clock  analogy,  freezing  is  equivalent  to  disconnecting  the  alarm  bell 
—  the  clock  continues  to  run  but  the  alarm  does  not  sound  unless  the  bell  is  reconnected. 

The  only  way  to  absolutely  disable  a  process  —  both  stopping  its  clock  and  preventing  any 
pending  events  to  get  through  —  is  to  freeze  and  block  it. 

Example: 
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**************************************************************************************** 

StopProcess  —  freeze  a  process  timer  and  block  any  pending  events 

UnstopProcess  —  unfreeze  and  unblock  the  process 

Pass:  X  =  process  number 

Returns:  x  unchanged 

Destroys:  a 


StopProcess: 

jsr        FreezeProcess  ;not  that  it  really  matters,  but  we'll  freeze  first 

jmp        BlockProcess  ;then  block  (let  BlockProcess  rts) 

UnstopProcess : 

jsr        UnblockProcess  ;unblock  first 

jmp        UnfreezeProcess  ;then  unfreeze  (let  Unf reezeProcess  rts) 


Forcing  a  Process  Event 

Sometimes  it  is  desirable  to  force  a  process  to  run  on  the  next  pass  through  MainLoop, 
independent  of  its  timer  value.  GEOS  provides  one  routine  for  this: 

plEnableProcess       Makes  a  process  runable  immediately.  H 

EnableProcess  merely  sets  the  runable  flag  in  the  hidden  process  table.  When  MainLoop 
encounters  a  process  with  this  flag  set,  it  will  attempt  to  generate  an  event,  just  as  if  the  timer  had 
decremented  to  zero.  This  means  that  EnableProcess  has  no  priveleged  status  and  cannot 
override  a  blocked  state.  However,  because  it  doesn't  depend  on  (or  affect)  the  current  timer  value, 
the  process  can  become  runable  even  with  a  frozen  timer. 


The  Nitty-gritty  of  Processes 


Processes  involve  a  complex  (but  hopefully  transparent  to  the  application)  interaction  between 
multiple  levels  of  GEOS.  In  advanced  uses,  it  may  be  necessary  to  understand  this  interaction.  The 
following  discussing  clarifies  some  of  the  fine  points  of  processes. 

Interrupt  Level  and  MainLoop  Level 

Processes  involve  two  distinct  levels  of  GEOS:  interrupt  level  and  MainLoop  level.  Every  vblank 
an  IRQ  (Interrupt  ReQuest)  signal  is  generated  by  the  computer  hardware.  Part  of  the  GEOS 
interrupt  service  routine  manages  process  timers:  if  a  process  exists  and  it  is  not  frozen,  its  timer  is 
decremented.  When  the  timer  reaches  zero,  the  interrupt  level  routine  sets  the  associated  runable 
flag  and  restarts  the  timer  with  its  initialization  value.  The  process  event  routine  is  not  called  at  this 
time. 

If  for  some  reason  interrupts  are  disabled  (usually  by  setting  the  interrupt  disable  flag  with  an  sei 
instruction)  and  a  vblank  occurs,  the  interrupt  will  be  ignored  and  the  process  timers,  therefore, 
will  not  be  decremented  during  that  vblank.  This  is  usually  not  a  problem  because  interrupts  are 
normally  enabled.  However,  be  aware  that  some  operating  system  functions  (such  as  disk  I/O) 
disable  interrupts. 
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During  a  normal  pass  through  MainLoop,  GEOS  will  examine  the  active  processes.  If  a 
process's  runable  flag  is  set  and  it  is  not  blocked,  MainLoop  clears  the  runable  flag  and  and  calls 
the  process.  If  a  process  is  blocked,  MainLoop  ignores  it. 

Because  of  the  way  MainLoop  and  the  interrupt  level  interact,  there  is  a  certain  level  of 
imprecision  with  processes: 

1:  If  a  process  has  a  very  low  timer  initialization  value  (e.g.,  less  than  five)  such  that  it  is 
possible  it  will  time-out  more  than  once  during  the  time  it  takes  for  a  single  pass  through 
MainLoop,  MainLoop  may  miss  some  of  these  time-outs.Each  time  the  timer  reaches 
zero  it  sets  the  runable  flag,  but  since  there  is  only  one  runable  flag  per  process, 
MainLoop  has  no  way  of  knowing  if  it  should  generate  more  than  one  event. 

2:  It  is  impossible  to  guarantee  any  precise  relationship  (e.g.,  a  timer  difference  less  than 
five)  between  two  or  more  timers.  Although  all  processes  that  time-out  during  the  same 
interrupt  will  become  runable  at  that  time,  the  interrupt  may  occur  while  MainLoop  is 
the  midst  of  handling  processes:  processes  that  have  already  been  passed-by  may  bee 
runable  but  not  get  executed  until  the  next  time  through  MainLoop,  which  could 
fraction  of  a  second  later. 


For  more  Information  refer  to  Chapter  @ML&INTS@. 


Process  Synchronization 

It  is  sometimes  desirable  to  maintain  a  synchronized  relationship  between  the  timer  values  of  two 
or  more  processes.  This  is  nontrivial  because  even  if  the  calls  to  restart,  freeze,  or  unfreeze  these 
timers  are  done  immediately  after  each  other,  there  is  always  a  slight  chance  that  the  vblank 

C interrupt  will  occur  after  the  status  of  some  of  the  timers  has  changed  but  before  all  have  been 
changed.  For  example:  if  an  application  is  trying  to  freeze  three  timers  simultaneously  and  the 
interrupt  happens  after  the  first  timer  has  been  frozen  but  before  the  other  two,  the  remaining  two 
timers  will  still  be  decremented.  To  circumvent  this  problem,  bracket  the  calls  by  disabling 
interrupts  before  freezing,  blocking,  or  restarting,  and  reenabling  afterward.  This  is  best  done  as  in 
the  following  example: 

RESTART  CLOCK  PRCXTESSES  AT  THE  SAME  TIME  *** 

f 

RstartP: 

php  ;save  interrupt  disable  flag 

sei  /disable  interrupts  (stopping  timers) 

Idx  tRTCLOCK                        /restart  clock 

jsr  RestartProcess 

Idx  #SCRNSAVER        /restart  screen-saver 

jsr  RestartProcess 

pip  /restore  interrupt  disable  status 

Disabling  Processes  While  Menus  Are  Down 

Because  MainLoop  is  still  running  when  menus  are  down,  process  events  continue  to  occur.  It  is 
often  desirable  to  disable  a  process  while  the  user  has  a  sub-menu  opened.  The  easiest  way  to 
handle  this  situation  is  to  check  menuNumber  at  the  beginning  of  the  process  event  routine.  If 
menuNumber  is  non-zero,  then  a  menu  is  down  and  the  event  routine  can  exit  early: 


PrEventRoutine : 

Ida       menuNumber  /check  menu  level 

bne        90$  ;and  exit  immediately  if  a  menu  is  down 

jsr       DoPrEvent  .  /else,  process  the  event  normally 

90$: 

rts  /return  to  MainLoop 
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Sleeping 


Sleeping  is  a  method  of  stopping  execution  of  a  routine  for  a  specified  amount  of  time.  That  is:  a 
routine  can  stop  itself  and  "go  to  sleep,"  requesting  MainLoop  to  wake  it  up  at  a  later  time.  GEOS 
provides  one  routine  for  sleeping: 


Sleep  does  not  actually  suspend  execution  of  the  processor.  When  the  application  does  a  jsr 
Sleep,  GEOS  sets  up  a  hidden  timer,  much  like  a  process  timer,  that  is  decremented  during  the 
vblank  interrupt.  It  removes  the  return  address  from  the  stack  (which  corresponds  to  the  jsr 
Sleep)  and  saves  it  for  later  use,  then  perfoms  an  rts.  Since  the  return  address  on  the  stack  no 
longer  corresponds  to  the  jsr  Sleep,  control  is  returned  to  a  jsr  one  level  lower.  In  many  cases, 
this  will  return  control  directly  to  MainLoop. 

When  the  timer  decrements  to  zero,  a  wake-up  flag  is  set,  and,  on  the  next  pass  through 
MainLoop,  the  sleeping  routine  will  be  called  with  a  jsr  to  the  instruction  that  immediately 
follows  the  jsr  sleep.  When  the  routine  finishes  with  an  rts  (or  another  jsr  Sleep),  MainLoop 
will  resume  processing. 

Important:    Any  temporary  values  pushed  onto  the  stack  must  be  pulled  off  prior  to  calling 


Sleep.  Also,  when  a  routine  is  awoken,  the  values  in  the  processor  registers  and 
the  GEOS  pseudoregisters  will  most  certainly  contain  different  values  from  when  it 
went  to  sleep.  This  is  because  MainLoop  has  been  running  full-speed,  calling 
events  and  doing  its  own  internal  processing,  thereby  changing  these  values.  If  a 
routine  needs  to  pass  data  from  before  it  sleeps  to  after  it  awakes,  it  must  do  so  in 
its  own  variable  space. 


Sleep  can  be  used  to  set  up  temporary,  run-once. processes  by  placing  calls  to  Sleep  inside 
subroutines.  For  example,  an  educational  program  may  want  to  flash  items  on  the  screen  and  make 
a  noise  when  the  student  selects  a  correct  answer.  The  routines  that  handle  these  "bells  and 
whistles"  can  be  established  using  Sleep  without  needlessly  complicating  the  function  that  deals 
with  correct  answers.  The  following  code  fragment  illustrates  this  idea: 


1^  Sleep 


Pause  execution  for  a  given  time  interval. 


*1^«****«*4r***********************************  ****************** 


Routine  to  handle  a  correct  answer.  Does  some  graphics,  makes 
some  noise,  and  adjusts  the  student's  score. 


*************************************************************** 


BELL^DELAY 
FLASH  DELAY 


60 
23 


; length  of  bell 

; delay  between  flashes 


Correct : 


IncW 
jsr 
jsr 
rts 


Bell 
Flash 


score 


/score  +«  1 

/start  the  bell  going 

/start  the  answer  flashing 
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Subroutine: 


If  sound  is  enabled  (user-determined),  start  the 
bell  sound  and  then  go  to  sleep;  Sleep 
returns  control  to  the  routine  that  called  us 


When  we  wake 
to  MainLoop 


up,  we  stop  the  be'll  sound  and  return 


Bell: 


90$: 


If  sound  is  disabled,  then  the  rts  returns 
directly  to  the  routine  that  called  us. 

Ida 

soundFlag 

/check  sound  flag 

beq 

90$ 

;exit  if  user  turned  sound  off 

jsr 

BellOn 

;else,  turn  the  bell  on 

LoadW 

rO,BELL_DELAY 

;and  delay  before  turning  off 

jsr 

Sleep 

;by  going  to  sleep  (think  rts) 

jsr 

BellOff 

;turn  bell  off  when  we  awake 

rts 

;exit 

Subroutine:     Invert  the  answer.  Go  to  sleep. 

answer  when  we  wake  up. 


Re-invert  the 


Flash: 


jsr 

LoadW 

jsr 

jsr 

rts 


InvAnswer 
rO,FLASH_DELAY 
Sleep 
InvAnswer 


; Graphically  invert  the  answer 
;and  delay  before  reverting 
/by  going  to  sleep  (think  rts) 
/when  we  awake,  revert  the  image 
/  exit 
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Math  Routines 


One  of  the  major  limitations  of  eight-bit  microprocessors  such  as  the  6502  is  their  math  capabilites: 
they  can  only  operate  directly  on  eight-bit  quantites  (0-255),  and  multiplication  and  division  require 
extensive  computational  energy.  For  the  sake  of  the  application  programmer,  GEOS  has  some  of 
the  more  popular  arithmetic  routines  built  into  the  Kemal.  These  include  double-precison  (two- 
byte)  shifting,  as  well  as  multiplication  and  divison. 

Parameter  Passing  to  Math  Routines 

The  math  routines  use  a  flexible  parameter  passing  convention:  rather  than  putting  values  into 
specific  GEOS  pseudoregisters,  the  application  can  place  the  values  in  any  zero-page  location 
(almost)  and  then  tell  GEOS  where  to  find  die  values  by  passing  the  address  of  the  of  the 
parameter.  Because  the  parameters  are  located  on  zero-page,  their  addresses  are  one-byte  quantites 
that  can  be  passed  in  the  x  and  y  index  registers.  For  example,  a  GEOS  math  routine  might  require 
two  word  values.  The  application  could  place  these  values  in  pseudoregisters  aO  and  al,  then  call 
a  GEOS  math  routine,  like  Ddiv  (double-precision  divide)  with  the  address  of  aO  and  al  in  the  x 
and  y  registers. 

Example: 

Idx  #aO  ;load  up  address  of  first  parameter 

Idy  #al  ;and  address  of  other  parameter 

jsr  Ddiv  /divide  the  word  in  aO  by  the  word  in  al 

Important:  It  is  easy  to  get  confused  and  leave  off  the  immediate-mode  sign  (#)  when  trying  to 
load  the  address  of  a  zero-page  variable,  thereby  loading  the  value  contained  in  the 
variable  instead. 


Double-precision  Shifting 

The  6502  provides  instructions  for  shifting  eight-bit  quantites  left  and  right  but  no  instructions  for 
directing  these  operations  on  16-bit  (double-precision)  numbers.  GEOS  provides  two  routines  for 
double-precision  shifting: 


•  DShiftLeft 

Arithmetically  left-shifts  a  16-bit  word  value. 

•  Di^hiftRight 

Arithmetically  right-shifts  a  16-bit  word  value. 

Double-Precision  Arithmetic 

Many  of  the  possible  double-precision  arithmetic  operations  (such  as  word+word  addition)  are 
provided  with  GEOS  macros.  The  standard  set  of  GEOS  macros,  which  include  the  likes  of 
AddW  and  SubW,  are  listed  in  Appendix  XX.  Many  double-precision  operations,  however,  such 
as  multiplication  and  division,  are  complicated  enough  to  warrant  an  actual  subroutine.  GEOS 
provides  many  of  these  routines,  some  of  which  have  signed  and  unsigned  incarnations. 
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Signed  vs.  Unsigned  Arithmetic 

6502  arithmetic  operations  rely  on  the  two's  complement  numbering  system  —  an  artifact  of  binary 
math  —  to  provide  both  signed  and  unsigned  operations  with  the  same  instructions  (ado  and  sbc). 
For  example,  an  ado  #$6c  can  be  seen  as  either  adding  188  to  the  accumulator  (unsigned  math:  all 
eight  bits  represent  the  positive  number,  any  carry  out  of  bit  7  indicates  an  overflow)  or  as  adding  a 
-68  to  the  accumulator  (signed  math:  the  high-bit,  bit  7,  holds  the  sign  and  any  carry  out  of  bit  6 
indicates  an  overflow).  The  6502  has' little  trouble  adding  and  subtracting  these  two*s-complement 
signed  numbers.  Operations  such  as  multiplication  and  division,  however,  need  to  special-case  the 
sign  of  the  numbers. 

Incrementing  and  Decrementing 

GEOS  has  only  one  routine  in  the  category  of  incrementing  and  decrementing: 

I  •  Ddec  Decrements  a  word,  setting  a  flag  if  the  value  reaches  zero.  | 

However,  because  incrementing  and  decrementing  words  are  such  common  operations,  Berkeley 
Softworks  has  created  a  set  of  macros  specifically  designed  for  incrementing  and  decrementing 
word  values: 

IncW 

Increment  Word  —  IncW  addr 

Args:     addr  —  address  of  word  to  increment 

Action:  IncW  increments  a  word.  If  the  result  is  zero, 

then  the  zero  flag  in  the  status  register  is  set. 

•  macro  IncW  addr 

inc        addr  /increment  low-byte 

,bne        done  /branch  if  no  carry  into  hi-byte 

inc        addr+1  /propagate  carry  into  hi-byte 

done:  /z-flag  is  set  if  both  hi  &  low  were  $00 

•  endm 

*★*★★**★★***★***★*★*★★*****★***★*****★*****★★*★**★******★*★*★**★★ 

DecW 

Decrement  Word  —  DecW  zpaddr 

Args:     zpaddr  —         zero-page  address  of  word  to  decrement 

Action:  DecW  Decrements  a  word.  If  the  result  is  zero, 

then  the  zero  flag  in  the  status  register  is  set. 
a  and  x  registers  are  destroyed. 

***************************************************************** 

•macro  DecW  zpaddr 

Idx        #zpaddr  /load  x  with  address  of  word  for  call 

jsr        Ddec  /call  GEOS  routine 

/z-flag  is  set  if  both  hi  &  low  were  $00 

•  endm 

k******************* ************* ************************ ******** 

Decrement  Word  #2         —         DecW2  addr 
(fast  version) 

Args:     addr  —  address  of  word  to  decrement 
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Action:  DecW2  decrements  a  word  with  inline  code.  No 

flags  are  set  on  reaching  $0000.  Destroys  a. 


.macro  DecW2  addr 

Ida  addr 

bne  noOvrflw 

dec  addr+1 

noOvrflw: 

dec  addr 

.endm 


;get  low  byte 

;if  low_byte  !=  $00,  then  skip  high  byte  dec 
/decrement  hi-byte 

/decrement  low-byte 


Most  applications  will  use  IncW  and  DecW  to  take  advantage  of  the  flags  which  are  set  when  the 
values  reach  zero.  However,  DecW2  can  be  useful  when  a  word  needs  to  be  decremented  quickly 
and  the  zero  flag  is  not  needed. 

Unsigned  Arithmetic 

GEOS  provides  the  following  routines  for  arithmetic  with  unsigned  numbers: 


•  BBMult 

Byte-by-byte  multiply:  multiplies  two  unsigned  byte  operands  to 
produce  an  unsigned  word  result. 

•  BMult 

Word-by-byte  multiply:  multiplies  an  unsigned  word  and  an 
unsigned  byte  to  produce  an  unsigned  word  result. 

•  DMuIt 

Word-by- word  (double-precision)  multiply:  multiplies  two 
unsigned  words  to  produce  an  unsigned  word  result. 

•Ddiv 

Word-by-word  (double-precision)  division:  divides  one  unsigned 
word  by  another  to  produce  an  unsigned  word  result. 

Example: 


ConvToUnits 

This  routine  converts  a  pixel  measurement  to  inches  or,  optionally, 
centimeters,  at  the  rate  of  80  pixels  per  inch  or  31.5  pixels  per 
centimeter . 

pass : 

rO  -  number  to  convert  (in  pixels) 

return : 

rO  -  inches  /  centimeters 

rlL  -  tenths  of  an  inch  /  millimeters 
affects: 

nothing 
destroys : 

a,  X,  y,  rO-rl,  r8-r9 

if  AMERICAN 


.  INCHES  «  TRUE 
.else     ; ! AMERICAN 

INCHES  =  FALSE 

.endif 


; decide  whether  inches  or  centimeters  is 
; appropriate 


ConvUnits : 
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.if 


INCHES 


;  First,  convert  rO  to  length  in  1/20  of 
/standard  units 

***  START  INCHES  SPECIFIC  CODE  *** 
For  ENGLISH,  need  to  multiply  by 
20  1 


Idx  #rO 

Idy  #2 

jsr  DShiftRight 

.else  /CENTIMETERS 


80  dots/inch  4 

which  amounts  to  a  divide  by  four 
(  /4  =  two  right  shifts) 

rO  =  r0»2      (rO  «  rO/4) 

;***  START  OF  CENTIMETER  SPECIFIC  CODE  *** 

For  centimeters,  need  to  do  multiply  by 
20  40 


31.5  dots/cm 
  Following  lines  changed  to  save  bytes 


63 


LoadW 

Idx 

Idy 

jsr 

LoadB 

Idx 

Idy 

jsr 

LoadW 

Idx 

Idy 

jsr 


.endif 


rl,#40 

#rO 

#rl 

DMult 

rl,#40 

#rO 

#rl 

BMult 

rl,#63 

#rO 

#rl 

Ddiv 


First  multiply  by  40 
(word  value) 
(byte  value) 

rO  «  rO*40  (byte  by  word  multiply) 
then  divide  by  63 


rO  =  rO/63 


START  OF  COMMON  CODE 


IncW 

LoadW 

Idx 

idy 

jsr 

MoveB 

Isr 

rts 


rO 

rl,#20 

#rO 

#rl 

Ddiv 

r8L,rlL 

rlL 


rO  »  result  in  l/20ths 

add  in  one  more  l/20th,  for  rounding 

now  divide  by  20  (to  move  decimal  over  one) 

dividend 

divisor 

rO  =  rO/20  (rO  =  result  in  proper  unit) 
rlL  «  l/20ths 

and  convert  to  1/lOths  (rounded) 
exit 


Signed  Arithmetic 

GEOS  provides  the  following  routines  for  arithmetic  with  signed  numbers: 


•  Dabs 

Computes  the  absolute  value  of  a  two's-complement  signed  word. 

•  Dnegate 

Negates  a  signed  word  by  doing  a  two's  complement  sign-switch. 

•  bSdiv 

Signed  word-by-word  (double-precision)  division:  divides  one 
two*s  complement  word  by  another  to  produce  an  signed  word 
result. 

There  is  no  signed  double-precision  multiply  routine  in  the  GEOS  Kemal.  The  following 
subroutine  can  be  used  to  multiply  two  signed  words  together. 
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DSir.ult  double-precision  signed  multiply. 

pass:   X  -  zpage  address  of  multiplicand 

y  -  zpage  address  of  multiplier 

returns:  signed  result  in  address  pointed  to  by  x 

word  pointed  to  by  y  is  absolute-value  of  the 

multiplier  passed- 
X,  y  unchanged 


/Strategy: 

Establish  the  sign  of  the  result:  if  the  signs  of  the 
;  multiplicand  and  the  multiplier  are  different,  then  the  result 

;  is  negative;  otherwise,  the  result  is  positive.  Make  both  the 

;  multiplicand  and  the  multiplier  positive,  do  unsigned 

/  multiplication  on  those,  then  adjust  the  sign  of  the  result 

;  to  reflect  the  signs  of  the  original  numbers. 

/destroys:         a,  r6  -  r8  (mgl) 

DSmult: 


Ida 

zpage+l, X 

;get  sign  of  multiplicand  (hi-byte) 

eor 

zpage+l,y 

;and  compare  with  sign  of  multiplier 

php 

;save  the  result  for  when  we  come  back 

jsr 

Dabs 

/multiplicand  =  abs (multiplicand) 

stx 

r6L 

;save  multiplicand  index 

tya 

;put  multiplier  index  into  x 

tax 

;for  call  to  Dabs 

jsr 

Dabs 

/multiplier  =  abs (multiplier) 

Idx 

r6L 

/restore  multiplier  index 

jsr 

Dmult 

/do  multiplication  as  if  unsigned 

pip 

/get  back  sign  of  result 

bpl 

90$ 

/ignore  sign-change  if  result  positive 

jsr 

Dnegate 

/otherwise,  make  the  result  negative 

rts 

« 

Dividing  by  Zero 

Division  by  zero  is  an  undefined  mathematical  operation.  The  two  GEOS  division  routines  (Ddiv 
and  DSdiv)  do  not  check  for  a  zero  divisor  and  will  end  up  returning  incorrect  results.  It  is  easy  to 
divide-by-zero  error  checking  to  these  two  routines: 

Example: 

/NewDdiv  —  Ddiv  with  divide-by- zero  error  checking 

/NewDSdiv  —  DSdiv  with  divide-by-zero  error  checking 


Pass : 

X 

zp  address  of  dividend 

y 

zp  address  of  divisor 

Returns 

x,y 

unchanged 

2p,x 

result 

r8 

remainder 

a 

$00        —  no  error 

%ff        —  divide  by  zero  error 

st 

set  to  reflect  error  code  in  accumulator 

Destroys 


r9 
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DIVIDE  BY  ZERO  =  $ff 


t*****************  f - ^ ************************************* 


NewDdiv : 

Ida 
ora 
bne 
Ida 
rts 


10$: 


Ida 
rts 


zpage,y 
2page,y 
10$ 

#DIVIDE  BY  ZERO 


Ddiv 
#$00 


;get  low  byte  of  divisor 

;and  high  byte  of  divisor 

;.if  either  is  non-zero,  go  divide 

/return  error 

;  exit 

! 

/divide 

;and  return  no  error 


NewDSdiv: 
Ida 
ora 
bne 
Ida 
rts 


10$: 


zpage,y 
zpage,y 
10$ 

#DIVIDE  BY  ZERO 


Apple 
stx 


.if 
.endif 

jsr  DSdiv 
.if  Apple 
Idx 

.endif 

Ida  #$00 

rts 


Xsave 


Xsave 


get  low  byte  of  divisor 

and  high  byte  of  divisor 

if  either  is  non-zero,  go  divide 

return  error 

exit 

save  x-register  because  Apple  destroys 


divide 

restore  x-register  because  that  ageos  destroyed 


and  return  no  error 


.if  Apple 

•ramsect 

Xsave     .block  1 

.psect 

.endif 


temp  x  register  save  variable  for  ageos 
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Text,  Fonts,  and  Keyboard  Input 

At  one  point  or  another,  almost  every  application  will  need  to  place  text  directly  on  the  screen  or  get 
keyboard  input  from  the  user. 

GEOS  text  output  facilities  support  disk-loaded  fonts,  multiple  point  sizes,  and  additive  style 
attributes.  The  application  can  use  GEOS  text  routines  to  print  individual  characters,  one  at  a  time, 
or  entire  strings,  including  strings  with  embedded  style  changes  and  special  cursor  positioning 
codes.  GEOS  will  automatically  restrict  character  printing  to  margins  allowing  text  to  be  confined 
within  screen  or  window  edges.  GEOS  even  contains  a  routine  for  formatting  and  printing  decimal 
integers. 

GEOS  keyboard  input  facilities  the  translation  of  keyboard  input  to  text  output  by  mapping  most 
keypress  so  that  they  correspond  to  the  printable  characters  within  the  GEOS  ASCII  character  set. 
GEOS  will  buffer  keypresses  and  use  them  to  trigger  MainLoop  events,  giving  the  application 
full  control  of  keypresses  as  they  arrive.  And  if  desired,  GEOS  can  also  automate  the  process  of 
character  input,  prompting  the  user  for  a  complete  line  of  text. 

Text  Basics 


Fonts  and  Point  Sizes 

Fonts  come  in  various  shapes  and  sizes  and  usually  bear  monikers  like  BSW  9,  Hwnbolt  12,  and 
Boalt  10.  A  font  is  a  complete  set  of  characters  of  a  particular  size  and  typeface.  In  typesetting,  the 
height  of  a  character  is  measured  in  points  (approximately  1/72  inch),  so  Humbolt  12  would  be  a 
12  point  (1/6  inch)  Humbolt  font.  A  text  point  in  GEOS  is  similar  to  a  typesetter's  point:  when 
printed  to  the  screen,  each  GEOS  point  corresponds  to  one  screen  pixel.  GEOS  printer  drivers  map 
screen  pixels  to  1/80  inch  dots  on  the  paper  to  work  best  with  80  dot-per-inch  printers.A  GEOS 
1/80  inch  point  is,  therefore,  very  close  to  a  typsetter's  1/72  inch  point. 

GEOS  has  one  resident  font,  BSW  9  (Berkeley  Softworks  9  point).  The  application  can  load  as 
many  additional  fonts  as  memory  will  allow.  Fonts  require  approximately  one  to  three  kilobytes  of 
memory. 

Proportional  Fonts 

Computer  text  fonts  are  typically  monospaced  fonts.  The  characters  of  a  monospaced  font  are  all 
the  same  width,  compromising  the  appearance  of  the  thinnest  and  widest  characters.  GEOS  fonts 
arc  proportional  fonts,  fonts  whose  characters  are  of  variable  widths.  Proportional  fonts  tend  to 
look  better  than  monospaced  fonts  because  thinner  characters  occupy  less  space  than  wider 
characters;  a  lower-case  "i,"  for  example,  is  often  less  than  l/5th  the  width  of  an  upper-case  "W." 

Character  Width  and  Height 

Although  some  characters  are  taller  than  others,  all  characters  in  a  given  font  are  treated  as  if  they 
are  the  same  height.  This  height  is  the  font's  point  size.  A  10  point  font  has  a  height  of  ten  pixels. 
If  a  character's  image  is  smaller  than  10  pbcels,  it  is  because  its  definition  includes  white  pixels  at 
the  top  or  bottom.  The  height  of  the  current  font  is  stored  in  the  GEOS  variable  curHeight. 
Although  fonts  taller  than  28  points  are  rare  (some  megafonts  are  as  tall  as  48  points),  a  font  could 
tiieoretically  be  as  tall  as  255  points. 
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Because  GEOS  uses  proportional  fonts,  the  width  of  each  character  is  determined  by  its  pixel 
definition  —  the  tiiinner  characters  occupy  fewer  pixels  horizontally  than  the  wider  characters. 
Most  character  definitions  include  a  few  columns  of  white  pixels  on  the  right  side  so  that  the  next 
character  will  print  an  appropriate  distance  to  the  right  If  this  space  didn't  exist,  adjacent  characters 
would  appear  crowded.  The  width  of  any  single  character  cannot  exceed  57  pixels  after  adding  any 
style  attributes,  which  means  that  the  plaintext  version  of  the  character  can  be  no  wider  than  54 
pixels. 

The  Baseline 

Each  font  has  a  baseline,  an  imaginary  line  that  intersects  the  bottom  half  of  its  character  images. 
The  baseline  is  used  to  align  the  characters  vertically  and  can  be  thought  of  as  the  line  upon  which 
characters  rest.  The  baseline  is  specified  by  a  relative  pixel  offset  from  the  top  of  the  characters  (the 
baseline  offset).  Any  portion  of  a  character  that  falls  below  the  baseline  is  called  a  descender.  For 
example,  an  18  point  font  might  have  a  baseline  offset  of  15,  which  means  that  the  15th  pixel  row 
of  the  character  would  rest  on  the  baseline.  Any  pixels  in  the  16th,  17th,  or  18th  row  of  the 
character's  definition  form  part  of  a  descender.  The  baseline  offset  for  the  current  font  is  stored  in 
the  GEOS  variable  baselineOffset.  The  application  may  increment  or  decrement  the  value  in  this 
variable  to  print  subscript  or  superscript  characters 

The  following  diagram  illustrates  the  relationship  between  the  baseline  and  the  font  height: 


The  y-position  passed  to  GEOS  printing  routines  usually  refers  to  the  position  of  the  baseline,  not 
the  top  of  the  character.  Most  of  the  character  will  appear  above  that  position,  with  any  descender 
appearing  below.  If  it  is  necessary  to  print  text  relative  to  the  top  of  the  characters,  a  simple 
transformation  can  be  used: 

charYPos  =  graphics  YPos  +  baselineOffset 

Where  graphicsYFos  is  the  true  pixel  position  of  the  top  of  the  characters,  charYPos  is  the 
transformed  position  to  pass  to  text  routines,  and  baselineOffset  is  the  value  in  the  global 
variable  of  that  name. 

Styles 

The  basic  character  style  of  a  font  is  called  plaintext.  Applying  additional  5fy/e  attributes  to  the 
plaintext  modifies  the  appearance  of  the  characters.  There  are  five  available  style  attirbutes:  reverse, 
italic,  bold,  outline,  and  underline.  These  styles  may  be  mixed  and  matched  in  any  combination, 
resulting  in  hybrids  such  as  bold  italic  underline.  The  current  style  attributes  are  stored  in  the 
variable  currentMode.  Whenever  GEOS  outputs  a  character,  it  first  alters  the  image  (in  an 
internal  buffer)  based  on  the  flags  in  this  variable: 
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Action : 


DecW2  decrements  a  word  with  inline  code.  No 
flags  are  set  on  reaching  $0000.  Destroys  a. 


.macro  DecW2  addr 

Ida  addr 

bne  noOvrflw 

dec  addr+1 

noOvrflw: 

dec  addr 

.endm 


;get  low  byte 

;if  low^byte  !=  $00,  then  skip  high  byte  dec 
/decrement  hi-byte 

/decrement  low-byte 


Most  applications  will  use  IncW  and  DecW  to  take  advantage  of  the  flags  which  are  set  when  the 
values  reach  zero.  However,  Dec\V2  can  be  useful  when  a  word  needs  to  be  decremented  quickly 
and  the  zero  flag  is  not  needed. 

Unsigned  Arithmetic 

GEOS  provides  the  following  routines  for  arithmetic  with  unsigned  numbers: 


•  BBMult 

Byte-by-byte  multiply:  multiplies  two  unsigned  byte  operands  to 
produce  an  unsigned  word  result. 

•  BMult 

Word-by- byte  multiply:  multiplies  an  unsigned  word  and  an 
unsigned  byte  to  produce  an  unsigned  word  result. 

•  DMuIt 

Word-by-word  (double-precision)  multiply:  multiplies  two 
unsigned  words  to  produce  an  unsigned  word  result. 

•Ddiv 

Word-by-word  (double-precision)  division:  divides  one  unsigned 
word  by  another  to  produce  an  unsigned  word  result. 

Example: 


ConvToUnits 

This  routine  converts  a  pixel  measurement  to  inches  or,  optionally, 
centimeters,  at  the  rate  of  80  pixels  per  inch  or  31.5  pixels  per 
centimeter . 

pass : 

rO  -  number  to  convert  (in  pixels) 

return : 

rO  -  inches  /  centimeters 

rlL  -  tenths  of  an  inch  /  millimeters 
affects : 

nothing 
destroys : 

a,  X,  y,  rO-rl,  r8-r9 

********************************************************* 

if  AMERICAN 


; decide  whether  inches  or  centimeters  is 
; appropriate 


.  INCHES  =  TRUE 
.else     ; ! AMERICAN 

INCHES  =  FALSE 

.endif 


ConvUnits: 


Math  Routines 


.if 


INCHES 


;  First,  convert  rO  to  length  in  1/20  of 
/standard  units 

***  START  INCHES  SPECIFIC  CODE  *** 
For  ENGLISH,  need  to  multiply  by 
20  1 


Idx  #rO 

Idy  #2 

jsr  DShiftRight 

.else  /CENTIMETERS 


80  dots/inch  4 

which  amounts  to  a  divide  by  four 
(  /4  =  two  right  shifts) 

rO  =  r0»2      (rO  =  rO/4) 

;***  START  OF  CENTIMETER  SPECIFIC  CODE  *** 

For  centimeters,  need  to  do  multiply  by 
20  40 


31.5  dots/cm 
  Following  lines  changed  to  save  bytes 


63 


LoadW 

Idx 

Idy 

jsr 

LoadB 

Idx 

Idy 

jsr 

LoadW 

Idx 

Idy 

jsr 


rl,#40 

#r0 

#rl 

DMult 

rl,#40 

#r0 

#rl 

BMult 

rl,#63 

#r0 

#rl 

Ddiv 


.endif 


IncW 

LoadW 

Idx 

idy 

jsr 

MoveB 

Isr 

rts 


rO 

rl,#20 

#r0 

#rl 

Ddiv 

r8L,rlL 

rlL 


First  multiply  by  40 
(word  value) 
(byte  value) 

rO  =  rO*40  (byte  by  word  multiply) 
then  divide  by  63 


rO  =  rO/63 


;***  START  OF  COMMON  CODE  *** 

rO  =  result  in  l/20ths 
add  in  one  more  l/20th,  for  rounding 
now  divide  by  20  (to  move  decimal  over  one) 
dividend 
divisor 

rO  =  rO/20  (rO  =  result  in  proper  unit) 
rlL  -  l/20ths 

and  convert  to  1/lOths  (rounded) 
exit 


Signed  Arithmetic 

GEOS  provides  the  following  routines  for  arithmetic  with  signed  numbers: 


•  Dabs 

Computes  the  absolute  value  of  a  two's-complement  signed  word. 

•  Dnegate 

Negates  a  signed  word  by  doing  a  two's  complement  sign-switch. 

•  DSdiv 

Signed  word-by-word  (double-precision)  division:  divides  one 
two*s  complement  word  by  another  to  produce  an  signed  word 
result. 

There  is  no  signed  double-precision  multiply  routine  in  the  GEOS  Kemal.  The  following 
subroutine  can  be  used  to  multiply  two  signed  words  together. 


4 


Math  Routines 


DSmult  double-precision  signed  multiply. 

pass:   X  -  zpage  address  of  multiplicand 

y  -  zpage  address  of  multiplier 

returns:  signed  result  in  address  pointed  to  by  x 

word  pointed  to  by  y  is  absolute-value  of  the 

multiplier  passed- 
X,  y  unchanged 


/Strategy: 

Establish  the  sign  of  the  result:  if  the  signs  of  the 
multiplicand  and  the  multiplier  are  different,  then  the  result 
;  is  negative;  otherwise,  the  result  is  positive.  Make  both  the 

;  multiplicand  and  the  multiplier  positive,  do  unsigned 

/  multiplication  on  those,  then  adjust  the  sign  of  the  result 

/  to  reflect  the  signs  of  the  original  numbers. 

/destroys:         a,  r6  -  r8  (mgl) 

DSmult: 


Ida 

2page+l, X 

;get  sign  of  multiplicand  (hi-byte) 

eor 

zpage+1, y 

;and  compare  with  sign  of  multiplier 

php 

;save  the  result  for  when  we  come  back 

jsr 

Dabs 

/multiplicand  =  abs (multiplicand) 

stx 

r6L 

;save  multiplicand  index 

tya 

/put  multiplier  index  into  x 

tax 

/for  call  to  Dabs 

jsr 

Dabs 

/multiplier  =  abs (multiplier) 

Idx 

r6L 

/restore  multiplier  index 

jsr 

Dmult 

/do  multiplication  as  if  unsigned 

pip 

/get  back  sign  of  result 

bpl 

90$ 

/ignore  sign-change  if  result  positive 

jsr 

Dnegate 

/otherwise,  make  the  result  negative 

rts 

4 

Dividing  by  Zero 

Division  by  zero  is  an  undefined  mathematical  operation.  The  two  GEOS  division  routines  (Ddiv 
and  DSdiv)  do  not  check  for  a  zero  divisor  and  will  end  up  returning  incorrect  results.  It  is  easy  to 
divide-by-zero  error  checking  to  these  two  routines: 

Example: 


-k  ic  *  ie  *  it  * -k -k  it  it  it  it  it  it  it  it  it  ic  it  It  it  It  it  it  it -k  it  1i  it  it*  It  icic -kit  it -kit  it  it  it  It  it  it  it  it  it  it  it* 

NewDdiv  —  Ddiv  with  divide-by-zero  error  checking 

—  DSdiv  with  divide-by-zero  error  checking 


NewDSdiv 
Pass : 


Returns 


Destroys 


X  zp  address  of  dividend 

y  zp  address  of  divisor 

x,y  unchanged 

zp,x  result 

r8  remainder 

a  $00        —  no  error 

%ff        —  divide  by  zero  error 

St  set  to  reflect  error  code  in  accumulator 

r9 


Math  Routines 


DIVIDE  BY  ZERO  =  $ff 


NewDdiv : 


10$: 


Ida 
ora 
bne 
Ida 
rts 

jsr 
Ida 
rts 


2page,y 
2page,y 
10$ 

#DIVIDE  BY  ZERO 


Ddiv 
#$00 


/get  low  byte  of  divisor 

;and  high  byte  of  divisor 

;.if  either  is  non-zero,  go  divide 

/return  error 

;  exit 

/ 

/divide 

/and  return  no  error 


NewDSdiv: 
Ida 
ora 
bne 
Ida 
rts 


10$: 


zpage,y 
zpage, y 
10$ 

#DIVIDE  BY  ZERO 


Apple 
stx 


.if 
.endif 

jsr  DSdiv 
.if  Apple 
Idx 

.endif 

Ida  #$00 

rts 


Xsave 


Xsave 


get  low  byte  of  divisor 

and  high  byte  of  divisor 

if  either  is  non-zero,  go  divide 

return  error 

exit 

save  x-register  because  Apple  destroys 


divide 

restore  x-register  because  that  ageos  destroyed 


and  return  no  error 


•if  Apple 

.ramsect 

Xsave     .block  1 

.psect 

.endif 


temp  x  register  save  variable  for  ageos 
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Text,  Fonts,  and  Keyboard  Input 

At  one  point  or  another,  almost  every  application  will  need  to  place  text  directly  on  the  screen  or  get 
keyboard  input  from  the  user. 

GEOS  text  output  facilities  support  disk-loaded  fonts,  multiple  point  sizes,  and  additive  style 
attributes.  The  application  can  use  GEOS  text  routines  to  print  individual  characters,  one  at  a  time, 
or  entire  strings,  including  strings  with  embedded  style  changes  and  special  cursor  positioning 
codes.  GEOS  will  automatically  restrict  character  printing  to  margins  allowing  text  to  be  confined 
within  screen  or  window  edges.  GEOS  even  contains  a  routine  for  formatting  and  printing  decimal 
integers. 

GEOS  keyboard  input  facilities  the  translation  of  keyboard  input  to  text  output  by  mapping  most 
keypress  so  that  they  correspond  to  the  printable  characters  within  the  GEOS  ASCII  character  set. 
GEOS  will  buffer  keypresses  and  use  them  to  trigger  MainLoop  events,  giving  the  application 
full  control  of  keypresses  as  they  arrive.  And  if  desired,  GEOS  can  also  automate  the  process  of 
character  input,  prompting  the  user  for  a  complete  line  of  text. 

Text  Basics 


Fonts  and  Point  Sizes 

Fonts  come  in  various  shapes  and  sizes  and  usually  bear  monikers  like  BSW  9,  Humbolt  12^  and 
Boalt  10.  A  font  is  a  complete  set  of  characters  of  a  particular  size  and  typeface.  In  typesetting,  the 
height  of  a  character  is  measured  in  points  (approximately  1/72  inch),  so  Humbolt  12  would  be  a 
12  point  (1/6  inch)  Humbolt  font.  A  text  point  in  GEOS  is  similar  to  a  typesetter's  point:  when 
printed  to  die  screen,  each  GEOS  point  corresponds  to  one  screen  pixel.  GEOS  printer  drivers  map 
screen  pixels  to  1/80  inch  dots  on  the  paper  to  work  best  with  80  dot-per-inch  printers.A  GEOS 
1/80  inch  point  is,  therefore,  very  close  to  a  typsetter's  1/72  inch  point. 

GEOS  has  one  resident  font,  BSW  9  (Berkeley  Softworks  9  point).  The  application  can  load  as 
many  additional  fonts  as  memory  will  allow.  Fonts  require  approximately  one  to  three  kilobytes  of 
memory. 

Proportional  Fonts 

Computer  text  fonts  are  typically  monospaced  fonts.  The  characters  of  a  monospaced  font  are  all 
the  same  width,  compromising  the  appearance  of  the  thinnest  and  widest  characters.  GEOS  fonts 
are  proportional  fonts,  fonts  whose  characters  are  of  variable  widths.  Proportional  fonts  tend  to 
look  better  than  monospaced  fonts  because  thinner  characters  occupy  less  space  than  wider 
characters;  a  lower-case  "i,"  for  example,  is  often  less  than  l/5th  the  width  of  an  upper-case  "W." 

Character  Width  and  Height 

Although  some  characters  are  taller  than  others,  all  characters  in  a  given  font  are  treated  as  if  they 
are  the  same  height.  This  height  is  the  font's  point  size.  A  10  point  font  has  a  height  of  ten  pixels. 
If  a  character's  image  is  smaller  than  10  pbcels,  it  is  because  its  definition  includes  white  pixels  at 
the  top  or  bottom.  The  height  of  the  current  font  is  stored  in  the  GEOS  variable  curHeight. 
Although  fonts  taller  than  28  points  are  rare  (some  megafonts  are  as  tall  as  48  points),  a  font  could 
theoretically  be  as  tall  as  255  points. 
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Because  GEOS  uses  proportional  fonts,  the  width  of  each  character  is  determined  by  its  pixel 
definition  —  the  thinner  characters  occupy  fewer  pixels  horizontally  than  the  wider  characters. 
Most  character  definitions  include  a  few  columns  of  white  pixels  on  the  right  side  so  that  the  next 
character  will  print  an  appropriate  distance  to  the  right  If  this  space  didn*t  exist,  adjacent  characters 
would  appear  crowded.  The  width  of  any  single  character  cannot  exceed  57  pixels  after  adding  any 
style  attributes,  which  means  that  the  plaintext  version  of  the  character  can  be  no  wider  than  54 
pixels. 

The  Baseline 

Each  font  has  a  baseline,  an  imaginary  line  that  intersects  the  bottom  half  of  its  character  images. 
The  baseline  is  used  to  align  the  characters  vertically  and  can  be  thought  of  as  the  line  upon  which 
characters  rest.  The  baseline  is  specified  by  a  relative  pixel  offset  from  the  top  of  the  characters  (the 
baseline  offset).  Any  portion  of  a  character  that  falls  below  the  baseline  is  called  a  descender.  For 
example,  an  18  point  font  might  have  a  baseline  offset  of  15,  which  means  that  the  15th  pixel  row 
of  the  character  would  rest  on  the  baseline.  Any  pixels  in  the  16th,  17th,  or  18th  row  of  the 
character's  definition  form  part  of  a  descender.  The  baseline  offset  for  the  current  font  is  stored  in 
the  GEOS  variable  baseh'neOffset.  The  application  may  increment  or  decrement  the  value  in  this 
variable  to  print  subscript  or  superscript  characters 

The  following  diagram  illustrates  the  relationship  between  the  baseline  and  the  font  height: 


The  y-position  passed  to  GEOS  printing  routines  usually  refers  to  the  position  of  the  baseline,  not 
the  top  of  the  character.  Most  of  the  character  will  appear  above  that  position,  with  any  descender 
appearing  below.  If  it  is  necessary  to  print  text  relative  to  the  top  of  the  characters,  a  simple 
transformation  can  be  used: 

charYPos  =  graphicsYPos  +  baselineOffset 

Where  graphicsYPos  is  the  true  pixel  position  of  the  top  of  the  characters,  charYPos  is  the 
transformed  position  to  pass  to  text  routines,  and  baselineOffset  is  the  value  in  die  global 
variable  of  that  name. 

Styles 

The  basic  character  style  of  a  font  is  called  plaintext.  Applying  additional  5fy/e  attributes  to  the 
plaintext  modifies  the  appearance  of  the  characters.  There  are  five  available  style  attirbutes:  reverse, 
italic,  bold,  outline,  and  underline.  These  styles  may  be  mixed  and  matched  in  any  combination, 
resulting  in  hybrids  such  as  bold  italic  underline.  The  current  style  attributes  are  stored  in  the 
variable  currentMode.  Whenever  GEOS  outputs  a  character,  it  first  alters  the  image  (in  an 
internal  buffer)  based  on  the  flags  in  this  variable: 
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0 


b7 

underline:  1  =  on;  0  =  off. 

b6 

boldface:  1  =  on;  0  =  off. 

b5 

reverse:  1  =  on;  0  =  off. 

b4 

italic:  1  =  on;  0  =  off. 

b3 

outline:  1  =  on;  0  =  Off. 

b2t 

superscript:  1  =  on;  0  =  off. 

bit 

subscript:  1  =  on;  0  =  off. 

bO 

unused.  

tSuperscript  and  subscript  characters  are  not  supported  by  the  standard  text  routines.  However,  geoWrite 
uses  these  bits  in  its  ruler  escapes.  An  application  can  print  superscript  and  subscript  by  characters  by 
changing  the  value  in  baselineOffset  before  printing:  subtracting  a  constant  will  superscript  the 
following  characters  and  adding  a  constant  will  subscript  the  following  characters.  Additionally,  some  Apple 
GEOS  printer  drivers  support  these  two  bits  when  SetMode  is  used  to  format  ASCII  output. 

Normally  it  is  not  necessary  to  modify  the  bits  of  currentMode  directly.  Special  style  codes  can 
be  embedded  directly  in  text  strings. 

Style  attributes  temporarily  modify  the  plaintext  definition  of  the  character  and,  in  some  cases, 
change  the  size  and  ultimate  shape  of  the  character: 


Underline 

Inverts  the  pixels  of  the  line  beloy^  the  baseline.  The  size  of  the  character 
does  not  change. 

Boldface 

The  character  image  is  shifted  onto  itself  by  one  pixel.  The  width  of  the 
character  increases  by  one. 

Outline 

Transforms  the  character  into  an  oudine  style.  This  transformation  occurs 
after  boldfacing  and  underUning.  //e^^/^A  4  \h^c>4^  ^^u^e^^ 

Italic 

Pairs  of  lines  above  the  baseline  are  shifted  right  and  pairs  of  lines  below 
the  baseline  are  shifted  left.  Thus  the  baseline  is  not  changed,  the  two 
lines  above  it  are  shifted  to  the  right  one  pixel,  the  next  two  are  shifted 
four  pixels  from  their  original  position,  and  so  forth.  The  effect  of  this  is 
to  take  the  character  rectangle  and  lean  it  into  a  parallelogranL  The  width  is 
not  actually  changed.  The  same  number  of  italicized  characters  will  fit  on  a 
line  as  non-italicized  characters,  and  because  the  shifting  is  consistent 
from  character  to  character,  adjacent  italic  characters  will  appear  next  to 
each  other  correctly.  However,  if  a  non-italic  character  immediately 
follows  an  italic  character,  the  non-italic  character  will  overwrite  right  side 
of  the  shifted  italic  character.  This  can  be  avoided  by  inserting  an  italicized 
space  character. 

Reverse 

Reverses  the  pixel  image  of  the  character.  This  is  the  last  transformation  to 
take  place.  Thz    Sx2f   J}o6^  /v^^  OVW/vtc. 

Note:  Although,  at  this  time,  style  attributes  affect  the  printed  size  of  a  character  in  a 
predictable  fashion,  the  application  should  not  perform  these  calculations  itself  but  use 
the  GEOS  GetRealSize  routine  to  ensure  compatibility  with  future  versions  of  the 
operating  system.  For  more  information,  refer  to  "Calculating  Character  WidthCin  diis 

 chapter.  \^  
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How  GEOS  Prints  Characters 


When  a  character  is  printed,  a  rectangular  area  the  width  of  the  character  and  the  height  of  the 
current  font  is  stamped  onto  the  background,  leaving  cleared  pixels  surrounding  the  character. 
When  writing  to  a  clear  background,  tihe  cleared  pixels  around  the  character  will  mesh  with  the 
cleared  background,  leaving  no  trace.  But  when  writing  to  a  patterned  background,  the  background 
will  be  overwritten: 


Is  stampea^\ 
background.  J 


There  is  no  simple  way  to  print  to  a  non-cleared  background  without  getting  clear  pixels 
surrounding  the  characters.  Solutions  usually  involve  accessing  screen  memory  direcdy. 


Text  and  dispBufferOn 

Like  graphics  routines,  most  text  routines  use  the  special  bits  in  dispBufferOn  to  direct  printing 
to  the  foreground  screen  or  the  background  buffer  as  necessary.  For  more  information  on  using 
dispBufferOn,  refer  to  "Display  Buffering"  in  Chapter  @GR@. 

GEOS  128  Character  X-position  Doubling 

GEOS  128  text  routines  pass  character  x-coordinates  through  NormalizeX,  allowing  automatic 
x-position  doubling.  (The  character  width  is  never  doubled,  only  the  x-position).  Character  x- 
position  doubling  is  very  much  like  graphic  x-positions  doubling  and  is  explained  in  "GEOS  128 
X-position  and  Bitmap  Doubling"  in  Chapter  @GR@.  There  is  one  notable  difference:  because 
smallPutChar  will  accept  negative  x-positions  (allowing  characters  to  be  clipped  at  the  left  screen 
screen  edge),  die  DOUBLE_W  and  ADD1_W  constants  should  be  bitwise  exclusive-or'ed  into 
the  x-positions  as  opposed  to  merely  bitwise"br*ed  This  will  maintain  the  correct  sign  information 
with  negative  numbers. 


Character  Codes 

Each  character  in  GEOS  is  referenced  by  a  single-byte  code  called  a  character  code.  GEOS 
character  codes  are  based  upon  the  ASCII  character  set,  offering  128  possible  characters 
(numbered  0-127).  GEOS  reserves  the  first  32  codes  (0-31)  as  escape  codes.  Escape  codes  are 
non-printing  characters  that  provide  special  functions,  such  as  boldface  enabling  and  text-cursor 
positioning.  Character  codes  32  through  126  represent  the  95  basic  ASCII  characters,  consisting  of 
upper-  and  lower-case  letters,  numbers,  and  punctuation  symbols.  The  127th  character  is  a  special 
deletion  character,  a  blank  space  as  wide  as  the  widest  character,  used  internally  for  deleting  and 
backspacing. 

Most  GEOS  fonts  do  not  offer  characters  for  codes  above  127  except  in  one  special  instance:  the 
standard  system  character  set  (BSW  9)  includes  a  128th  character  that  is  a  visual  representation  of 
the  shortcut  key  (a  Commodore  symbol  on  Commodore  computers  and  a  filled  Apple  logo  on 
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Apple  computers).  There  is  no  inherent  limitation  in  the  text  routines  that  would  prevent  an 
application  from  printing  characters  corresponding  to  codes  129  through  159,  assuming  the  current 
font  has  image  definitions  for  these  character  codes.  The  printing  routines  cannot  handle  character 
codes  beyond  159,  however.  The  text  routines  do  no  range-checking  on  character  codes;  do  not  try 
to  print  a  character  that  does  not  exist  in  the  current  font. 

A  complete  list  of  GEOS  character  codes  appears  in  Appendix  @TBL@, 

Printing  Single  Characters 

GEOS  will  print  text  at  the  string  level  or  at  the  character  level.  The  high-level  string  routines, 
where  many  characters  are  printed  at  once,  will  often  provide  all  the  text  facilities  an  application 
evers  need  outside  the  environment  of  a  dialog  box.  However,  in  return  for  generality,  string-level 
routines  sacrifice  some  of  the  flexibility  offered  by  character  level  routines.Character  level  routines, 
where  text  is  printed  a  character  at  a  time,  require  the  application  to  do  some  of  the  work:  deciding 
which  character  to  print  next  and  where  to  place  it.  Because  of  this  overhead,  t  is  tempting  to 
dispense  with  text  at  the  character  level,  relying  entirely  on  the  string  level  routines  instead.  But  the 
character  level  routines  are  the  basic  text  output  building  blocks  and  the  string  level  routines  depend 
upon  them  gready.  For  this  reason,  it  helps  to  understand  character  output  even  when  dealing 
entirely  with  string-level  output 

GEOS  provides  two  character-level  routines  that  are  available  in  all  configurations  of  GEOS: 


•  PutChar  Process  a  single  character  code.  Processes  escape  codes  and  only 

prints  the  character  if  it  lies  entirely  within  the  left  and  right 
 margins  (leftMargin,  rightMargin).  ^ 

•  SmallPutChar        Draw  a  single  character.  Does  not  check  margins  for  proper 

placement.  Does  not  handle  escape  codes.  Prints  partial  characters, 
clipping  at  margin  edges. 

And  one  routine  that  only  exists  in  Apple  GEOS: 

•  EraseCharacter      Erase  a  character  from  the  screen,  accounting  for  the  current  font 

and  style  attributes. 

PutChar  is  the  basic  character  handling  routine.  It  will  attempt  to  print  any  character  within  the 
range  32  through  256  ($20  through  $ff)  as  well  as  process  any  escape  codes  (character  codes  less 
than  32),  such  as  style  escapes.  It  will  also  check  to  miake  sure  that  the  character  image  will  fit 
entirely  within  the  left  and  right  margins.  SmallPutChar,  on  the  other  hand,  carries  none  of  the 
overhead  necessary  for  processing  escape  codes  and  checking  margins;  it  is  smaller  (hence,  the 
name)  and  faster  but  requires  that  Ae  application  send  it  appropriate  data.  Do  not  send  escape  codes 
to  SmallPutChar. 

Typically  an  application  will  call  PutChar  in  a  loop,  using  SmallPutChar  to  print  a  portion  of  a 
character  that  crosses  a  marpn  boundary.  SmallPutChar  can  also  be  used  by  an  appUcation  that 
does  its  own  range-checking,  thereby  avoiding  any  redundancy.  Be  sure  to  only  send 
SmallPutChar  character  codes  for  printable  characters. 

PutChar  and  Margin  Faults 

Ptior  to  printing  a  character,  PutChar  checks  two  system  variables,  leftMargin  and 
rightMargin.  When  an  application  is  first  run,  these  two  margin  variables  default  to  the  screen 
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edges  (0  and  SC_PIX_WIDTH-1,  respectively).  If  any  part  of  the  current  character  will  fall 
outside  one  of  these  two  margins,  the  character  is  not  printed.  Instead,  GEOS  jsr's  through 
stringFaultVec  with  the  following  parameters: 

rll  Character  x-position.  If  the  character  exceeded  the  right  margin,  then  this  is  the 
position  GECSs  tried  to  place  the  offending  character.  If  the  character  fell  outside  of 
the  left  margin,  then' the  width  of  the  offending  character  was  added  to  the  x- 
position,  making  this  the  position  for  the  next  character. 

r  1 H    Character  y-position. 

Note:  When  Apple  GEOS  vectors  through  StringFaultVec,  the  current  values  of  rll  and 
rlH  are  stored  on  the  alternate  zero-page.  Do  a  sta  ALTZP_ON  before  accessing 
them  and  a  sta  ALTZP_OFF  after  accessing  them.  When  the  string  fault  routine 
returns,  PutChar  will  automatically  copy  these  working  registers  over  to  the  main 
zero-page. 


StringFaultVec  defaults  to  $0000.  Because  GEOS  uses  the  conditional  jsr  mechanism, 
CallRoutine,  a  $0000  will  cause  character  faults  to  be  ignored. 

There  are  many  ways  to  handle  a  margin  faults  (including  ignoring  them  entirely), .  Faults  on  the 
left  margin  are  usually  ignored  or  not  even  bothered  with  because  printing  will  usually  begin 
predictably  at  the  left  margin,  thereby  precluding  that  type  of  fault.  But  faults  on  the  right  margin, 
(which  are  less  predictable)  will  often  get  special  handling,  such  as  using  SmallPutChar  to 
output  the  fractional  portion  of  the  character  that  lies  to  the  left  of  rightMargin. 

There  is  one  unfortunate  problem  with  faults  through  PutChar:  the  fault  routine  has  no  direct  way 
of  knowing  which  character  should  be  printed  and  so  will  lose  some  of  its  generality  by  needing 
access  to  chta  that  should  be  local  to  the  routine  that  calls  PutChar.  One  simple  way  around  this 
problem  is  to  use  a  global  variable  —  call  it  something  like  lastChar  —  to  hold  the  character  code 
of  the  character  being  printed,  or  perhaps,  make  it  a  pointer  into  memory  (PutString  does  just  that 
with  rO).  This  way  the  fault  routine  will  faiow  which  character  caused  the  fault. 

Example: 

/macro:  PutChar  char  (char  «  character  code) 

;  Macro  to  replace  jsr  PutChar  in  your  code  so  that  lastChar 

;  holds  the  value  of  the  last  character  printed 

.***************************************************************** 

.macro  PutChar  character 

sta        lastChar  ; character  is  already  in  A-reg 

jsr  PutChar 

.endm 

Calculating  the  Size  of  a  Character 

Text  foraiatting  techniques  such  as  right  justification  require  the  application  to  know  the  size  of  a 
character  before  it  is  printed.  GEOS  offers  two  routines  for  calculating  the  size  of  a  character: 
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•  GetCharWidth 

Calculates  the  pixel  width  of  a  character  as  it  exists  in  the  font  (in 
its  plaintext  form).  Ignores  any  current  style  attributes. 

•  GetRealSize 

Calculates  the  pixel  height,  width,  and  baseline  offset  for  a 
character,  accounting  for  any  style  attributes. 

These  routines  can  be  used  in  succession  to  calculate  the  printed  size  of  any  character  combination, 
whether  groups  of  random  characters,  individual  words,  or  complete  sentences. 

Partial  Character  Clipping 

Confining  text  output  to  a  window  on  the. screen  is  called  clipping.  Characters  that  will  appear 
outside  the  window*s  margins  are  not  printed;  they  are  "clipped,"  so  to  speak.  Sometimes, 
however,  it  is  desirable  to  print  the  portion  of  the  offending  character  that  lies  within  the  margin 
and  only  clip  the  portion  that  lies  outside  the  window  area.  This  sort  of  clipping  is  called  partial 
character  clipping. 

Top  and  Bottom  Character  Clipping 

Both  PutChar  and  SmallPutChar  handle  top  and  bottom  partial  character  clipping.  Any  portion 
of  a  character  that  lies  outside  of  the  vertical  range  specified  by  windowTop  and 
windowBottom  will  not  be  printed.  windowTop  and  windowBottom  default  to  the  full 
screen  dimensions  (0  and  SC_PIX_HEIGHT-1,  respectively).  They  may  be  changed  by  the 
application  before  printing  text"  " 

Left  and  Right  Character  Clipping  with  SmallPutChar 

Whenever  a  character  crosses  the  left  or  right  margin  boundary,  PutChar  vectors  through 
StringFaultVec  without  printing  the  character.  SmallPutChar,  unlike  PutChar,  will  not 
generate  string  faults.  If  a  character  crosses  a  margin  boundary,  SmallPutChar  will  print  the 
portidn  of  the  character  that  lies  within  the  margin. 

SmallPutChar  will  also  accept  small  negative  values  as  the  character  x-position,  allowing 
characters  to  be  clipped  at  the  left  screen  edge  by  placing  leftMargin  at  0. 

Note:  Clipping  at  the  left  margin,  including  negative  x-position  clipping,  is  not  supported  by 
early  versions  of  GEOS  64  (earlier  than  version  1.4)  —  the  entire  character  is  clipped 
instead.  Left  margin  clipping  is  supported  on  all  other  version  of  GEOS:  GEOS  64 
vl.4  and  above,  GEOS  128  (in  botii  64  and  128  mode),  and  Apple  GEOS.  Early 
versios  of  Apple  GEOS  (versions  earlier  than  2.0.3)  did  not  properly  clip  at  the  left- 
margin. 


Manual  Character  Clipping 

Once  of  the  criticisms  of  GEOS  is  the  iconsistent  and  sometimes  capricious  character  clipping 
capabilities  —  not  all  versions  of  GEOS  fully  support  partial  character  clipping  and  the  versions 
that  do  have  inherent  ideosyncracies.  A  carefully  desilwd  program  can  usually  work  around  these 
limitations.  Some  applications,  however,  will  need  a  reliable  method  to  perform  partial  character 
clipping.  The  following  ClipChar  subroutine  will  properly  clip  and  print  a  character  Aat  partially 
exceeds  one  of  the  left  or  right  margins.  Be  aware  that  ClipChar  does  quite  a  bit  of  caculation  and 
should  only  be  used  in  special  cases  where  controlled  character  clipping  is  needed. 

Example: 
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.if  (0) 

ClipChar  —  print  a  character,  clipping  to  window  margins. 

Description: 

Draw  a  character,  clipping  it  EXACTLY  to  leftMargin,  rightMargin, 
windowTop  and  windowBottom 

Operates  by  temporarily  modifying  the  font  definition  (making  the 
character  thinner,  so  as  to  fit  in  the  margin) . 


Pass : 

a  -  character  to  print 
rll  -  X  position 
rlH  -  y  position 

Return : 

rll  -  X  position  for  next  char 
rlH  -  y  position  for  next  char 


Destroyed: 

a,  X,  y,  r2-rlOL 

.endif 
ClipChar: 
sta 


\e  It  tt  It  ic -k  *  *  *  it -k  H 


tit*it*1t'kittt1tiftftt'ttitit1tiHt 


Idx 
jsr 
dey 
tya 
add 
sta 
Ida 
adc 
sta 


rlL 
currentMode 
GetRealSize 


rllL 

r2L 

#0 

rllH 
r2H 


store  character 
get  width  of  character 

use  width  -  1  to  calc  last  position 

r2  =  last  pixel  that  char  covers 


3$: 


5$: 


10$: 


CmpW 

r2, leftMargin  , 

•cfteck  for  char  entirely  off  window 

bit 

3$ 

•if  so  then  exit 

CmpW 

rightMargin, rll  , 

bge 

5$ 

AddWVW 

r2,l,rll                       ;rll  «  one  pixel  beyond  where  char  would 

rts 

;  exit 

Ida 

rlL 

•push  old  width  table  values 

sub 

#32 

?get  card  # 

sta 

r3L 

asl 

a 

tay 

Idx 

#0 

Ida 

(curlndexTable) , y 

•store  this  char's  index  values 

sta 

savedWidths,x  < 

iny 

inx 

cpx 

#4 

bne 

10$ 

'loop  to  copy  values 

CmpW 

leftMargin, rll  , 

bit 

30$ 

Ida 

r3L 

asl 

a  1 

tay 

Ida 

leftMargin  , 

check  for  clipping  on  left 
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30$: 


50$: 


60$: 


sub 

rllL 

clc 

adc 

(curlndexTable) , y 

sta 

(curlndexTable) , y 

inv 

Ida 

#0 

adc 

(curlndexTable) ,y 

sta 

(curlndexTable) ,y 

MoveW 

leftMargin, rll 

CmpW 

r2, rightMargin 

bit 

50$ 

Ida 

r2L 

sub 

rightMargin 

sta 

r3H 

Ida 

r3L 

asl 

a 

tav 

iny 

iny 

Ida 

(curlndexTable) , y 

sub 

r3H 

sta 

(curlndexTable)  ,y . 

iny 

Ida 

(curlndexTable)  ,y 

sbc 

#0 

sta 

(curlndexTable) , y 

Ida 

rlL 

pha 

jsr 

SmallPutChar 

pla 

sub 

#32 

asl 

a 

tay 

Idx 

#0 

Ida 

savedWidths,  X 

sta 

(curlndexTable)  ,y 

iny 

inx 

cpx 

#4 

bne 

60$ 

rts 

check  for  clipping  on  right 
save  amount  to  subtract 


draw  the  character  ! ! 
save  it  for  later 


recover  old  widths 


, ramsect 
savedWidths : 

.block  4 
•psect 


/values  from  index  tabel  stored  here 


Printing  Decimal  Integers  (PutDecimal) 

One  of  the  unfortunate  side-effects  of  binary  math  is  the  conversion  necessary  to  print  numbers  in 
decimal.  Fortunately,  GEOS  offers  a  routine  to  remove  this  drudgery  from  the  application: 

rnputPecimal  Format  and  print  a  1 6-bit,  positive  integer  H 

PutDecimal  is  like  a  combination  of  character  and  string  level  routines.  The  application  passes  it 
a  single  16-bit,  positive  integer,  some  formatting  codes  (e.g.,  right  justify,  left  justify,  suppress 
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leading  zeros),  and  a  printing  position.  PutDecimal  converts  the  binary  number  into  a  series  of 
one  to  five  numeric  characters  and  calls  PutChar  to  output  each  one. 

String  Level  Routines 

Many  applications  will  never  need  complex  text  output  and  can  rely  on  GEOS's  string-level 
routines  for  simple  text  output  and  input.  GEOS  provides  two  string-level  text  routines,  one  for 
printing  strings  to  the  screen  and  one  for  getting  strings  through  the  keyboard 


•  PutString 

Print  a  string  to  the  screen. 

•  GetString 

Get  a  string  from  the  keyboard  using  a  cursor  prompt  and  echoing 
characters  to  the  screen  as  they  are  typed. 

GEOS  Strings 

A  GEOS  string  is  a  null-terminated  group  of  character  codes.  (Null-terminated  means  the  end  of 
the  string  is  marked  by  a  NULL  character  ($00).)  These  strings  can  contain  alphanumeric 
characters  as  well  as  special  escape  codes  for  changing  the  style  attributes  or  changing  the  printing 
position. 

There  is  no  basic  limit  to  the  possible  length  of  a  string;  GEOS  processes  the  string  one  character  at 
a  time  until  it  encounters  the  NULL,  which  it  interprets  as  the  end  of  the  string.  If  the  string  is  not 
terminated,  GEOS  will  have  way  of  knowing  where  the  end  of  the  string  is  and  will  continue 
printing  until  it  encounters  a  $00  in  memory. 

A  simple  string  of  ASCII  characters  might  look  like  this: 

Stringl : 

.byte     "This  is  a  simple  string NULL 

The  above  string,  including  the  NULL,  is  25  characters  long  (and  therefore  25  bytes  long  also). 
Escape  codes  may  be  emb^ded  within  the  string  to  effect  changes  while  printing.  An  individual 
word,  for  example,  may  be  underlined  by  embedding  an  ULINEON  escape  code  before  the  word 
and  an  ULINEOFF  after  it  as  in: 

String2 : 

.byte     "This  word  is  " 

.byte     OLINEON,  "underlined",  ULINEOFF,".",  NULL 

The  embedded  escape  codes  change  the  style  attribute  bits  in  currentMode  mid-string,  resulting 
in  something  like: 

This  word  is  underlined. 

PutString 

PutString  offers  a  simple  way  to  handle  text  output.  It  is  really  does  nothing  more  than  call 
PutChar  in  a  loop,  so  issues  that  apply  to  PutChar,  such  as  top  and  bottom  character  clipping, 
also  apply  to  PutString.  PutString  directly  supports  a  feature  that  PutChar  doesn't,  though: 
muWbyte  escape  codes,  such  as  GOTOXY,which  require  rO  to  contain  a  pointer  to  the  auxUiary 


1  0 


Fonts,  and  Keyboard  Input 


bytes  in  a  multibyte  sequence  (PutString  maintains  rO  automatically,  allowing  the  extra 
parameters  to  be  embedded  directly  in  the  string).  Printing  a  string  to  the  screen  with  PutString 
involves  specifying  a  position  to  begin  printing  and  passing  a  pointer  to  a  null-tenninated  string: 

Example: 


Example  use  of  PutString.  Places  a  test  string  onto  the 
screen.  Assumes  that  leftMargin,  rightMargin,  windowTop  and 
windowBottom  contain  their  default,  startup  values  (full 
screen  dimensions) . 


Print : 


String: 


STR_X 

=  40 

;x-position  of  first  character 

STR_Y 

=  100 

;y-position  of  character  baseline 

LoadB 

dispBuffOn,#(ST_WR_ 

JORE  1  ST_WR_BACK)             ;both  buffers 

LoadW 

rll,#STR__X 

/string  x-postion 

LoadB 

rlH,#STR__Y 

/string  y-position 

LoadW 

rO,#String 

/address  of  text  string 

jsr 

PutString 

/print  the  string 

rts 

/exit 

.byte 

"This  is  a  test.", 

NULL          /null-terminated  string 

String  Faults  (Left  or  Right  Margin  Exceeded) 

Because  PutString  calls  PutChar,  if  any  part  of  the  current  character  will  fall  outside  of 
leftMargin  or  rightMargin,  the  character  is  not  printed.  Instead,  GEOS  jsr's  through 
stringFaultVec  with  the  following  parameters: 

rll  Character  x-position.  If  the  character  exceeded  the  right  margin,  then  this  is  the 
position  GEOS  tried  to  place  the  offending  character.  If  the  character  fell  outside  of 
the  left  margin,  then  the  width  of  the  offending  character  was  added  to  the  x- 
position,  making  this  the  position  for  the  next  character. 

r  1 H    Character  y-position. 

rO  Pointer  to  the  offending  character  in  the  string.  Only  valid  with  PutString,  unused 
by  Putchar. 

Note:  When  Apple  GEOS  vectors  through  StringFaultVec,  the  current  values  of  rll,  and 
rlH,  and  rO  are  stored  on  the  alternate  zero-page.  Do  a  sta  ALTZP_ON  before 
accessing  them  and  a  sta  ALTZP^OFF  after  accessing  them.  When  the  string  fault 
routine  returns,  PutString  will  automatically  copy  these  working  registers  over  to  the 
main  zero-page> 

GEOS  64  and  GEOS  128  do  nothing  special  to  handle  these  string  faults.  If  the  application  has  not 
installed  its  own  string  fault  routine,  stringFaultVec  it  should  contain  a  default  value  of  $0000, 
which  will  cause  the  string  fault  to  be  ignored.  If  this  is  the  case,  the  following  will  happen: 

•  If  part  of  the  character  was  outside  of  the  left  margin,  the  width  of  the  offending 
character  was  added  to  the  x-position  in  rll  before  the  fault.  PutString  moves  on  to 
the  next  character  in  the  string  and  attempts  to  print  it  at  this  new  position. 
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•  If  part  of  the  character  was  inside  the  left  margin  but  outside  the  right  margin, 
PutString  leaves  the  x-position  unchanged  and  moves  on  to  the  next  character  in  the 
string. 

The  strategy  behind  this  system  is  to  only  print  the  portion  of  the  string  that  lies  entirely  within  the 
left  and  right  margins.  Unfortunately,  this  strategy  is  flawed.  Whenever  the  right  margin  is 
encountered,  PutString  should  stop  completely.  But  it  doesn't.  It  continues  searching  through 
the  string,  looking  for  a  character  that  will  fit.  This  can  be  a  problem  when  a  thin  character  follows 
a  wide  character.  For  example,  trying  to  print  the  word  "working"  with  only  a  few  pixels  of  space 
before  the  right  margin,  PrintString  would  try  to  print  the  "w,"  but  since  it  doesn't  fit,  would 
move  on  and  try  its  luck  with  the  following  "o."  But  the  "o"  won't  fit  either,  so  it  moves  on  until  it 
encounters  the  "i,"  which  just  happens  to  fit  in  the  available  space.  PutString  proudly  prints  the 
"i,"  thinking  it  has  done  a  good  thing,  entirely  unaware  that  the  proper  sequence  of  characters  has 
been  lost. 

The  Apple  GEOS  version  of  PutString  offers  a  partial  solution  to  this  problem.  If 
stringFaultVec  contains  $0000,  it  installs  a  temporary  string  fault  routine  (PutStringFault). 
PutStringFault  immediately  terminates  string  printing  on  any  fault  (left  or  right  margin)  by 
moving  rO  forward  to  point  to  the  null.  To  disable  the  Apple  PutStringFault  so  that  Apple 
GEOS  PutString  is  identical  to  GEOS  64  and  GEOS  128  PutString,  point  StringFaultVec  to 
an  rts  prior  to  calling  PutString.  PutStringFault  can  be  implemented  on  GEOS  64  and  GEOS 
128  by  placing  the  following  routine  into  StringFaultVec  prior  to  calling  PutString: 


PutStrFault      (for  GEOS  64/128  only) 


String  fault  routine  for  duplicating  the  Apple  GEOS  PutString 
fault  handling  on  GEOS  64  and  GEOS  128.  Immediately  terminates 
string  printing  when  any  fault  (left  or  right  margin)  is 
generated  by  setting  rO  to  point  at  the  end  of  the  string. 

*******************  € 


PutStrFault : 


;Go  through  the  string  looking  for  the  null 

Idy  #1  ;load  index  to  look  at  next  character 

bne  ^'-^"'0$  4        M'      ; always  branch  —  don't  inc  on  1st  pass 


20$: 

IncW  rO  /check  next  character 

10$:      Ida  (rO),y  ;get  character 

bne  20$  ;loop  until  we  find  null 


/Return  to  PutString  pointing  at  a  null 
rts 


The  above  technique,  however,  has  two  flaws:  if  a  character  lies  outside  the  left  margin,  printing  is 
aborted,  and,  with  either  type  of  fault,  the  application  has  no  way  of  knowing  wjiich  character  in 
the  string  caused  the  fault.  The  following  routine,  SmartPutString,  will  solve  both  these 
problems.  If  a  character  lies  outside  the  left  margin,  it  is  skipped,  and  if  it  lies  outside  the  right 
margin,  SmartPutString  returns  with  rO  pointing  to  the  character  in  the  string  that  caused  it  to 
terminate.  If  rO  points  to  a  NULL,  then  SmartPutString  was  able  to  print  the  whole  string  and 
terminated  noraially. 

.if  0 

. ****** ************* ************* *********************** ********** 

; SmartPutString 
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New  front-end  to  PutString  that  handles  right-edge  string 
;  faults  by  exiting  immediately  rather  than  moving  through 

/  the  string  until  it  finds  a  character  that  fits.  It  operates 

by  replacing  the  current  string  fault  service  routine  with 
its  own  routine  that  tricks  PutString  into  thinking  it 
;  encountered  a  null  on  a  right -margin  fault. 

/  Pass:     same  as  PutString.  The  string  must  not  be  located 

in  zero-page  ($00-$f f) . 

;  Returns:  same  as  PutString,  except  that  if  the  string 

;  faulted,  then  rl5  points  to  the  offending  character 

rather  than  the  null  at  the  end  of  the  string.  If 
rl5  =  $0000,  then  the  string  printed  without  a  fault 

;  Destroys:  same  as  PutString. 

;  Note:     No  inline  support. 

.endif 

SmartPutString : 

/Insert  our  own  string  fault  routine  into  stringFaultVec, 
; saving  the  old  one  so  that  we  can  restore  it  when  we  leave. 
PushW     StringFaultVec  ;save  old 

LoadW     StringFaultVec, #FaultFix         ; install  new 

; Clear  the  flag  that  alerts  us  to  a  right-edge  fault.  If  the  high 
;byte  of  rl5  is  zero  then  PutString  returns  immediately  because 
;our  string  never  encountered  the  right  edge. 

LoadW    rl5,#0  ; clear  rl5  to  $0000 

;Call  PutString  with  our  string  fault  routine  in  place 
jsr  PutString 

90$: 

; Restore  the  old  string  fault  routine 
PopW  StringFaultVec 

; Return 

rts 
;FaultFix 

;Our  own  string  fault  routine  that  sets  up  the  string  'pointer 
;so  that  PutString  is  tricked  into  thinking  it  encountered  a 
;NULL  when  the  right  margin  is  exceeded. 

FaultFix: 

; Check  to  see  if  we  exceeded  the  right  margin  or  if  we  just 
; haven't  reached  the  left  margin  yet.  If  the  right  margin  was 
;not  exceeded,  return  early  —  the  text  routine  handles  this, 
•case  appropriately. If  the  first  character  in  the  string  will  not 
;fit  within  either  margin,  we  treat  it  as  if  the  right  margin  was 
; exceeded.  Don't  need  to  normalize  the  coordinates  under  GEOS  128 
/because  the  character  output  routine  has  already  taken  care  of 
;this  for  us. 

.if        (APPLE)  /Apple  GEOS  hides  registers 
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sta        ALTZP_ON  ;on  aux.  zpage. 

.endif 

CmpW      rightMargin, rll  /check  x  with  right  edge 

ble        90$  ;exit  if  right  not  exceeded; 

;the  character  was  outside  the 

/left  edge. 

/Save  the  pointer  to  the  offending  character  in  rl5  (which  is  left 
/untouched  by  the  normal  PutString) 

Ida  rOL 

Idx  rOH 

.if         (APPLE)  /need  to  change  rl5  on  main  zp  if  apple 

sta  ALTZP__OFF 

.endif 

stx  rl5H 

sta  rl5L 

.if         (APPLE)  /return  Apple  to 

sta        ALTZP__ON  /aux.  zpage. 

.endif 

/Change  the  string  pointer  so  that  PutString  thinks  the  next 
/character  is  a  null. 

LoadW     rO,  #  (FakeNull-1)  /one  less  to  compensate  for 

/increment  that  PutString  will 

/do  before  it  checks. 

90$: 

/Return  to  let  PutString  do  its  stuff 
.if  (APPLE) 
sta  ALTZP__OFF 
.endif 

rts  /return  to  to  StringFault  caller 

FakeNull:  .byte     NULL  /null  for  FaultFix 

.  Embedding  Style  Changes  Within  a  String 

A  string  may  contain  embedded  escape  codes  for  changing  the  style  attributes  mid-string.  For 
example,  if  while  printing  a  string  GEOS  encounters  a  BOLDON  (24)  escape  code,  then 
PutString  will  temporarily  escape  from  normal  processing  to  set  the  boldface  bit  in 
currentMode.  Any  characters  thereafter  will  be  printed  in  boldface. 

Style  changes  are  typically  cumulative.  If  a  OUTLINEON  code  is  sent,  for  example,  then  the 
outline  style  attribute  will  be  added  to  current  set  of  attirbutes.  If  boldface  was  already  set,  then 
subsequent  characters  will  be  both  outiined  and  boldfaced.  The  PLAINTEXT  escape  code 
returns  text  to  its  normal,  unaltered  state. 

When  PutString  is  first  called,  it  begins  printing  in  the  styles  specified  by  the  value  in 
currentMode  and  when  it  returns,  currentMode  retains  the  most  recent  value,  reflecting  any 
style-change  escapes.  The  next  call  to  PutString  (or  any  other  GEOS  printing  routine)  will 
continue  printing  in  that  style.  To  guarantee  printing  in  a  particular  style  without  inheriting  any 
style  attributes  from  previous  strings,  the  first  character  in  the  string  should  be  a  PLAINTEXT 
escape  code.  Any  specific  style  escape  codes  can  then  follow. 

Position  Escapes  (Moving  the  Printing  Position  Mid-string) 

GEOS  provides  escape  codes  for  changing  the  current  printing  position.  Like  other  escape  codes, 
tiiese  can  be  embedded  within  the  string.  Some  of  them  are  simple,  such  as  LF  and  UPLINE, 
which  move  the  current  printing  position  down  one  line  or  up  one  line,  respectively,  based  on  the 
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height  of  the  current  font.  Others,  such  as  GOTOX,  GOTOY,  and  GOTOXY,  require  byte  or 
woni  pixel  coordinates  to  be  embedded  within  the  string  immediately  after  the  escape  code. 

Example: 

string: 

.byte  HOME  ; start  in  the  upper-left  corner 

.byte  LF  /move  down  one  line. so  we  have  room 

.byte  "This  ",LF,"is      LF, "stepping  ",LF- 

.  byte  "Down" , LF"ward" , CR 

.byte  LF,  "HELLO" 

.byte  GOTOXY 

.word  4  0  ;x-position 

.byte  15  ;y-position  of  baseline 

.byte  "Look!  I  moved." 

.byte  NULL 

Escaping  to  a  Graphics  String 

GEOS  provides  a  special  escape  code  (ESC_GRAPHICS)  that  takes  the  remainder  of  a  string 
and  treats  it  as  input  to  the  GraphicsString  routine.  This  allows  graphics  command  to  be 
embedded  within  a  text  string,  which  is  useful  for  creating  complex  displays,  especially  those  that 
require  graphics  to  be  drawn  over  text.  The  current  pen  positions  for  the  graphics  arc  unitialized  so 
the  first  graphics  string  command  should  be  a  MOVEPENTO. 

Example: 

TextGraphics : 

.byte  GOTOXY 
.word  20 
.byte  20 
.byte  "BOX: 
.byte  ESC__GRAPHICS 
.byte  MOVEPENTO 
.word  10 
.byte  10 

.byte  RECTANGLETO 
.word  50 
.byte  30 
.byte  NULL 

Note:  When  GraphicsString  encounters  the  NULL  marking  the  end  of  a  string,  control  is 
returned  to  the  application  as  if  PutString  had  terminated  normally.  The  NULL  does 
not  resume  PutString  processing. 

If  it  is  necessary  to  print  additional  text  after  graphics,  the  ESC^PUTSTRING 
command  may  be  used  to  escape  from  GraphicsString.  A  subsequent  NULL  will 
still  mark  the  end  of  the  string.  Be  aware  that  each  context-switch  between  these  two 
routines  allocates  additional  6502  stack  space  that  is  not  released  until  the  NULL 
terminator  is  encountered     


GetString 


; string  with  both  text  and  graphics 


GetString  provides  a  convenient  way  for  an  application  to  get  text  input  from  the  user  without 
using  a  dialog  box.  GetString  takes  care  of  intercepting  keypresses  and  echoing  the  characters  to 
the  screen.  The  beauty  of  GetString  is  that  it  builds  the  string  concurrently  with  the  rest  of 
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Unfortunately,  there  is  no  direct  way  to  terminate  GetString  before  the  user  presses  [Return]. 
The  trick  of  choice  in  this  situation  is  to  simulate  a  press  of  the  return  key  by  loading  keyData 
with  a  CR  and  vectoring  through  key  Vector  as  in: 


; simulate  a  CR  to  end  GetString 

LoadB     keyData,  #CR  ;load  up  a  CR  (Return)  key 

Ida        keyVector  .;and  vector  through  keyVector 

Idx        keyVector+1  ;so  SystemStringService  will 

jsr        CallRoutine  ;think  it  was  pressed  now 


This  same  technique  can  be  used  to  terminate  a  DB GETSTRING  when  an  icon  is  pressed  to 
leave  a  dialog  box. 

Note:  The  Apple  GEOS  version  of  GetString  always  keeps  the  partial  string  null-terminated 
while  it  is  building  it  in  the  buffer.  An  application  can  peek  at  the  status  of  the  string  by 
looking  in  this  buffer.  GEOS  64  and  GEOS  128  (through  vl.3)  do  not  null-terminate 

 the  string  until  [Return]  is  pressed  (or  simulated).  
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In  GEOS  a  font  is  a  complete  set  of  characters  of  a  particular  size  and  typeface.  On  disk,  fonts  are 
organized  by  style,  where  a  single  font  file  holds  all  the  available  point  sizes  for  a  given  style.  Each 
point  size  occupies  its  own  VLIR  record  in  the  font  file.  The  record  number  corresponds  to  the 
point  size.  For  example,  a  font  file  called  MyFont  might  use  three  VLIR  records,  one  for  each 
available  font  size:  the  MyFont  10  would  occupy  record  10,  MyFont  12  would  occupy  record  12, 
and  MyFont  24  would  occupy  record  24. 

It  is  the  job  of  the  application  to  decide  which  fonts  to  keep  in  memory  at  any  one  time,  reading  in 
the  appropriate  records  from  the  VLIR  font  file.  Once  a  font  is  in  memory  (usually  as  the  result  of  a 
call  to  ReadRecord),  the  application  must  inform  GEOS  to  begin  using  the  new  font  with  the 
following  routine: 

•  LoadCharSet  Instruct  GEOS  to  begin  using  a  new  font.  (Font  is  already  ir 
 memory.)  


Because  Apple  GEOS  allows  font  data  to  be  stored  in  auxiliary  memory,  an  additional  routine  is 
provided  for  doing  the  equivalent  of  LoadCharSet  when  the  font  is  in  auxiliary  memory 
(LoadCharSet  is  still  used  when  the  font  is  in  main  memory): 

•  LoadAuxCharSet    Instruct  GEOS  to  begin  using  a  new  font.  (Font  is  already  in 

auxiliary  memory.) 

Although  the  word  "Load"  in  LoadCharSet  and  LoadAuxCharSet  is  misleading  in  that  it 
implies  they  automatically  load  the  character  set  from  disk  into  memory,  the  application  must  read 
the  font  data  into  memory  prior  to  calling  these  routines.  LoadCharSet  and  LoadAuxCharSet 
expect  an  address  pointer  to  the  beginning  of  the  font  in  memory.  It  will  then  build  out  a  variable 
table  for  the  text  routines,  providing  information  such  as  the  baseline  offset  and  font  point  height. 
The  application  may  keep  as  many  fonts  resident  as  free  memory  will  allow,  switching  tiiem  at  will 
with  calls  to  LoadCharSet  and  LoadAuxCharSet .  Some  sophisticated  GEOS  applications  use 
a  font-cacheing  system  where  fonts  are  kept  in  memory  based  on  their  frequency  of  use. 

GEOS  provides  an  additional  routine  for  returning  to  the  always-resident  BSW  9  system  font: 
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I  •  UseSystemFont      Instruct  GEOS  to  begin  using  the  default  BSW  9  font. 
UseSystemFont  passes  the  address  of  the  the  system  BSW  9  font  to  LoadCharSet. 


The  Structure  of  a  Font  File 

Fonts  are  stored  in  VLIR  files  of  GEOS  type  FONT,  A  single  font  file  contains  all  the  available 
point  sizes  for  a  particular  style  (up  to  a  maximum  of  16).  Each  point  size  occupies  one  complete 
VLIR  record.  The  record  number  corresponds  to  the  point  size  (i.e.,  record  9  would  contain  the 
data  for  the  nine  point  character  set).  If  a  VLIR  record  in  a  font  file  is  empty,  then  the 
corresponding  point  size  is  not  available  (the  record  will  exist,  but  will  marked  as  empty  in  the 
index  table).  The  data  in  each  of  these  records  is  what  GEOS  considers  a  character  set,  and  its 
structure  is  described  later  in  "Character  Set  Data  Structure."  Unless  the  application  is  creating  or 
modifying  fonts,  this  data  structure  is  unimportant,^ 

The  font  files  on  a  given  disk  can  be  (ound^sing  the  FindFTypes  routine.  Once  the  font  files 
are  known,  the  application  can  us^  G5fflBfInft>>^o  access  the  header  block  for  each  font  file.  The 
font  file  header  block  contains  infotingtiojii^itineht  to  the  particular  font  file,  such  as  the  font  style 
ID,  the  available  point  sizes,  and  the  amount  of  memory  required  for  each  point  size.  These  values 
can  be  accessed  in  the  header  block  by  using  the  following  offsets: 


Offset 


Field  size  Description 


O  GHFONTID 

1  word 

Font  style  ID. 

O^GHPTSIZES 

16  words 

Character  set  ID's  for  those  available  in  this 
file.  Arranged  from  smallest  to  largest  point 
size.  Table  is  padded  with  zeros. 

16  words 

Size  (in  bytes)  of  each  character  set  from 
smallest  to  largest  point  size.  (These  numbers 
have  a  one-to-one  coorespondence  with  the 
O^GHPTSIZES  table.  Table  is  padded  with 
zeros. 

Every  font  style  has  a  unique  10-bit  ID  number.  This  number  is  stored  in  the  word-length  field 
O^GHFONTID.  The  next  field,  O^GHPTSIZES,  has  room  for  16  character  set  ID  numbers.A 
character  set  ID  number  is  a  16-bit  combination  of  the  style  ID  and  a  point  size  identifier.  The  style 
ID  is  stored  in  the  upper  10  bits  and  the  point  size  is  stored  in  the  lower  6  bits: 


Character  Set  ID  Wordt 


15      14      13      12      11      10      9        8        7        6        5       4       3       2        1  0 

I  10-bit  Style  ID  (b6-bl5)  I      point  size  (bO-b5) 

b6-bl5         Style  ID. 
bO-b5  Point  Size. 

This  combination  of  style  ID  number  and  point  size  gives  each  character  set  (font)  a  unique  word- 
length  identifier.  This  allows  any  style/point-size  combination  to  be  referenced  with  a  two-byte 
number.  For  example,  the  Durrant  style  has  a  style  ID  of  15,  so  the  Durrant  10  font  would  have  a 
character  ID  of 

(15  «  6)  I  10       or  $03ca 
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Berkeley  Softworks'  applications  use  the  NEWCARDSET  escape  followed  by  the  character  set 
ID  word  to  flag  font  changes  within  a  text  document 

Note:  A  complete  list  of  font  ID's  for  registered  fonts  appears  in  Chapter  XX.  Developers 
wishing  to  register  their  own  fonts  should  contact  Berkeley  Softworks  in  writing  for 
available  ID  numbers: 

Berkeley  Softworks 
Attn:  Font  Registration 
2150  Shattuck  Avenue 

Berkeley,  CA  94704 

Each  request  must  include  a  disk  with  the  font  files  along  with  the  desired  registration 
names. 


Character  Set  Data  Structure 

A  character  set  is  stored  —  both  in  memory  and  in  its  VLIR  record  —  as  a  contiguous  data 
structure  consisting  of  an  eight-byte  header,  followed  by  an  index  table  and  the  actu^  character 
image  data.  The  image  data  for  the  characters  are  stored  in  a  bitstream  format,  pixel  row  by  pixel 
row.  Imagine  laying  every  printable  character  side  by  side,  in  character  code  order,  starting  with 
character  number  32  (the  space  character).  If  the  top  row  of  pixels  from  every  character  were  then 
stored  together  as  a  contiguous  stream  of  bits,  this  would  be  the  proper  bitstream  format.  In 
GEOS,  for  every  pixel  of  height  in  a  character  set,  there  is  a  corresponding  bitstream  row.  Starting 
with  the  top  row,  each  bitstream  row  is  padded  with  zeros  to  make  it  end  on  a  byte  boundary.  The 
next  row  (if  there  is  one)  is  appended  at  the  next  byte.  The  number  of  bytes  in  each  bitstream  row 
is  called  the  set  width.J^ 

Because  each  character  in  a  GEOS  font  can  be  of  a  different  pixel  width,  GEOS  needs  some  way 
of  induing  into  the  bitstream  data  to  find  the  beginning  of  each  character.  For  each  character  there 
is  gjS»&Pindex  werfTfliat  indicates  where  the  character  begins  in  the  bitstream.  For  example,  if  the 
first  pixel  for  the  "A"  character  begins  at  pixel  148  in  the  bitstream,  then  the  index  value  for 
character  code  65  (uppercase  "A")  would  be  148. 
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Character  Set  Data  Structure 


Offset     Field  size       Description  IN 


uyic 

OaoCilllC  UiioCl  |(/lACio  irUili  LUp  UL  dlaiadCly. 

+1 

word 

Bytes  in  one  bitstream  row  (set  width). 

+3 

byte 

Font  height,  ("/vc^/^ 66/1.  o/^  rizr%rneAm  fio^%) 

+4 

word 

Pointer  to  beginning  of  index  table  (relative  to  beginning  of 
data  structure).  Usually  $0008  because  the  index  table 
follows  immediately  after  theiieader.  ^^Ah  WQrt/O . 

+6 

1  word 

Pointer  to  beginning  of  character  bitstream  data  (relative  to 
beginning  of  data  structure).  Bitstream  data  typically  follows 
the  index  table. 

^  • 

;  woras 

inciex  taoie.  one  wora  entry  lor  eacn  prmtaoie  cnaracter  (tne 
first  word  corresponds  to  character  code  32).  Each  index 
word  is  pixel  position  of  the  character  in  each  bitstream  row. 
Total  number  of  words  =  number  of  printable  characters  in 
the  set. 

+? 

?  bytes 

Bitstream  rows:  one  row  of  bitstream  data  for  each  pixel  of 
height  in  the  character  set.  Each  bitstream  row  ij  padded 
with  ztxoi^'^x  to  the  next  byte.  Total  bytes?^  number  of 
printable  characters  in  the  set  times  the  set  width. 

Saving  and  Restoring  the  Font  Variables 

In  both  GEOS  64  and  GEOS  128/^1  the  information  GEOS  needs  for  using  a  font  is  stored  in  the 
variable  table  beginning  at  fontTable  and  stretching  for  FONTLEN  bytes.  Whenever  GEOS 
needs  to  switch  fonts  internally  (while  drawing  the  BSW  9  text  fii^crtnenus,  for  example),  these 
bytes  are  saved  off  to  saveFontTab,  which  is  also  FONTLEN  bytes  long.  If  a  Commodore 
GEOS  application  needs  to  temporarily  change  fonts,  it  can  simply  duplicate  tins  technique,  saving 
and  restoring  between  fontTable  and  saveFontTab  as  needed. 

Under  Apple  GEOS,  however,  not  all  the  font  information  is  accessible  to  applications.  Apple 
GEOS,  therefore,  includes  two  routines  for  saving  and  restoring  all  the  necessary  font  table 
information  between  its  own  variables  and  saveFontTab: 


♦  SaveFontData 

Save  internal  font  data  to  saveFontTab. 

•  RestoreFontData 

Restore  internal  font  data  from  saveFontTab. 

An  application  should  never  return  to  MainLoop  with  valid  data  in  the  saveFontTab 
area^ecause  MainLoop  may  use  the  saveFontTab  area  for  its  own  purposes,  thereby 
destroying  any  font  information  that  may  be  saved  there.  Of  course,  the  information  in 
saveFontTab  can  always  be  copied  to  another  buffer  before  giving  MainLoop  control. 

When  GEOS  runs  a  desk  accessory,  it  saves  off  all  the  current  font  variables  to  a  special  area  of 
memory.  However,  the  temporal  saveFontTab  area  is  no(j;aved.  If  a  desk  accessory  uses 
menus,  the  menu  routines  will  use  the  area  at  saveFontTab,  thereby  overwriting  any  saved  data. 
Since  the  saveFontTab  area  is  not  saved  in  die  context  switch  between  the  application  and  the 
desk  accessory,  it  will  come  back  with  incorrect  data.  It  is,  therefore,  the  desk  accessory's  job  to 
save  and  restore  the  data  at  saveFontTab  if  necessary. 
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Keyboard  Input 

Many  keyboard  input  needs  can  be  accomodated  through  normal  processing  with  GetString  and 
through  dialog  boxes  with  DBGETSTRING,  but  many  specialized  functions  require  servicing 
keypresses  directly.  The  application  might  want  to  implement  shortcut  keys  —  special  key 
combinations  that  allow  quick  access  t&  menu  items  or  other  functions  —  or  an  application,  such  as 
a  word  processor,  might  need  to  do  dynamic  text  formatting  as  characters  are  typed. 

Key-scan  Conversion 

The  internal  code  that  the  computer  hardware  returns  for  each  keypress  usually  reflects  the  position 
of  the  key  on  the  keyboard,  not  the  actual  character  on  the  keycap.  GEOS  pre-processes  all 
keypresses,  ignoring  some  and  translating  others.  For  most  keys,  the  keypress  is  translated  into 
the  GEOS  ASCII  character  code  equivalent:  [a]  translates  to  97,  [SHIFT]  +  [a]  translates  to  65, 
and  [RETURN]  translates  to  CR.  These  keys  can  go  directly  to  GEOS  text  routines  wihtout  any 
further  work.  However,  there  are  some  key  combinations  that  get  translated  outside  of  the  printable 
character  range  (codes  between  0  and  32),  and  the  application  will  need  to  filter  these  out. 


Note:  Apple  GEOS  input  drivers  and  aux-drivers  both  have  the  opportunity  to  preprocess  or 
translate  keypresses  before  they  undergo  the  standard  GEOS  translation.  For  more 
information,  refer  to  KeyFilter  and  AuxDKeyFilter  in  the  Routine  Reference 
Section. 


If  the  shortcut  key  (designated  by  the  Commodore  logo  on  CBM  computers  and  the  filled  Apple 
logo  on  Apple  computers)  is  pressed  in  combination  with  another  key,  the  high-bit  (bit  7)  of  the 
keypress  byte  will  be  set.  This  means,  for  example,  that  [SHORTCUT]  +  [a]  is  equivalent  to 

.byte     (SHORTCUT  I  'aM 


How  GEOS  Handles  Keypresses 

At  interrupt  level,  GEOS  scans  the  keyboard  looking  for  a  key  presses  and  releases.  If  a  new  key 
has  been  pressed  or  an  old  key  has  been  held  down  long  enough  to  begin  auto-repeating,  GEOS 
places  the  corresponding  character  code  for  the  key  at  the  end  of  the  keyboard  queue.  The 
keyboard  queue  is  a  circular  FIFO  (first-in,  first-out)  buffer  that  holds  keypresses.  A  queue  is  used 
because  many  typists  can,  at  times,  type  keys  faster  than  the  application  can  process  them.  If  there 
was  no  key  buffer,  keypresses  would  be  lost.  As  long  as  there  are  characters  in  in  the  keyboard 
queue,  the  KEYPRESS^BIT  of  pressFlag  is  set. 

On  each  pass  through  MainLoop,  GEOS  checks  the  KEYPRESS^BIT  of  pressFIag.  If  the 
bit  is  set,  GEOS  removes  the  oldest  keypress  from  the  queue,  places  it  in  the  global  variable 
keyData,  and  attempts  to  vector  through  keyVector.  keyVector  usually  contains  a  $0000, 
which  causes  GEOS  to  ignore  the  vector  and,  hence,  ignore  the  keypress.  As  long  as  keyVector 
is  $0000,  keypresses  will  continue  to  accumulate  in  die  queue  at  interrupt  level  and  be  ignored,  one 
at  a  time,  at  MainLoop  level. 

By  placing  the  address  of  a  key-handling  routine  in  keyVector^  the  application  can  be  called  off 
of  MainLoop  to  process  keypresses  as  they  become  available.  When  the  application's  key  handler 
gets  called,  it  merely  picks  up  the  key  code  from  keyData,  does  any  necessary  processing,  and 
returns  to  MainLoop  with  an  rts  when  done. 
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With  this  technique,  though,  the  application  can  only  process  one  keypress  on  each  pass  through 
MainLoop,  even  though  the  keyboard  queue  may  have  more  than  one  character  in  it.  This  is 
typically  not  a  problem  because  the  overhead  most  applications  need  to  handle  a  character  is 
minimal.  But  take  geoWrite,  for  example.  If  only  one  character  could  be  processed  at  a  time,  it 
might  need  to  print,  word- wrap,  and  scroll  for  each  character.  Even  a  medium  speed  typist  could 
get  far  ahead  of  the  screen  updating.  If  there  was  a  way  to  get  at  all  the  keypresses  in  the  queue  at 
once,  then  all  the  calculating  and  screen  manipulations  could  be  done  for  more  than  one  character 
on  each  pass  through  MainLoop.  GEOS  offers  a  routine  to  do  just  this: 


I  •  GetNextChar         Retrieve  the  next  character  from  the  keyboard  queue!* 


J 


GetNextChar  gets  the  keycode  of  the  next  available  character  from  the  keyboard  queue  and 
returns  it  in  the  accumulator.  If  there  are  no  more  characters  available,  GetNextChar  returns  a 
NULL.  To  retrieve  all  the  queued  keypresses,  an  application  can  call  GetNextChar  in  a  loop, 
transferring  all  queued  characters  to  its  own  buffer.  This  buffer  must  be  at  least  KEY_QUEUE 
bytes  long  so  that  it  won't  be  overflowed. 


Example: 


KeyHandler 

Sample  key  handler.  Stuff  address  of  this  routine  into 
keyVector.  Unloads  the  keyboard  queue  into  an  internal 
buffer  but  does  nothing  with  the  characters. 


KeyHandler : 
Idx 
Ida 
sta 


#0 

keyData 
newKeys, X 


10$: 


php 
sei 

inx 
jsr 
sta 
cmp 
bne 

pip 


GetNextChar 
newKeys, X 
#NULL 
10$ 


; start  at  beginning  of  internal  buffer 
;get  first  keypress 
; store  it  in  my  buffer 

;lock  out  interrupts  for  a  moement 
;so  we  don't  get  any  new  keypresses 

/point  to  next  position  in  buffer 
;get  another  character 
;put  it  in  our  buffer 
;was  that  the  last 
;loop  back  to  get  more 

; restore  interrupt  disable  status 


/All  new  keys  are  now  in  our  buffer.  Our  buffer  is  conveniently 
/null-terminated  because  the  last  character  we  set  down  was  a 
/NULL.  Neat,  huh? 

jsr        DoNewKeys  /go  process  the  keys  we  picked  up 


99$: 

rts 

.ramsect 

newKeys:  .block  KEY_QUEUE+1 

.psect 


/return  to  MainLoop 
?max  queue  size  +  NULL 


DoNewKeys 

A  do-nothing  routine  that  just  pretends  to  empty  our  own 
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;  keyboard  buffer. 

DoNewKeys : 

Idx        #$00  ; start  at  beginning  of  buffer 

10$: 

Ida        newKeys,x  ;get  a  key 

beq        20$  -/exit  loop  if  it's  the  null 

nop  ;do  nothing  with  this  keypress 

inx  /point  to  next  position 

bne        10$  /always  branch  (X  should  never  go  to  0) 

20$: 

•We've  encountered  the  NULL  and  therefore  gone  through  the  entire 
/string.  Clear  the  buffer  by  storing  the  null  in  the  first 
/position  of  the  string, 
sta  newKeys+0 

99$: 

rts  /exit 


Ignoring  Keys  While  Menus  are  Down 

Becuase  MainLoop  is  still  running  full-speed  when  menus  are  down,  keyVector  will  still  ber 
vectored  through  on  a  regular  basis.  The  application  may  want  to  postpone  any  text  output  or 
keypress  interpretation  when  menus  are  down.  Checking  for  this  case  is  simple: 

Ida  menuNumber      [  /check  current  menu  level 

bne  99$  I-  ^       /leave  if  any  menus  are  down 

Implementing  Shortcuts 

Shortcut  keys  are  a  common  user-interface  facility  found  in  GEOS  applications.  Briefly,  a  shortcut 
key  is  a  key  combination  that  allows  the  quick  selection  of  a  menu  item  or  function  in  the 
application.  Typically  shortcuts  are  distinguished  from  other  keypresses  by  pressing  the  shortcut 
key  (the  Commodore  logo  or  the  filled  Apple  logo)  while  typing  another  key.  Key  combinations 
that  include  the  shortcut  key  will  have  the  high-bit  set,  which  maJkes  them  easy  to  recognize.  Even 
if  an  application  is  not  using  shortcuts,  it  will  most  likely  want  to  at  least  filter  out  all  shortcut  keys. 

To  process  shortcut  keys,  the  normal  key  handler  (the  one  the  application  installs  into  keyVector) 
should  first  check  the  high-bit  of  the  keypress  and  branch  to  the  shortcut  key  handler  if  the  bit  is 
set: 


KeyHandle: 

Ida 

menuNumber 

/check  current  menu  level 

bne 

99$ 

^           .  /ignore  keys  while  menus 

Ida 

keyData 

rrTget  the  keypress 

bmi 

10$ 

/was  it  a  shortcut? 

jsr 

NormalKey 

/no,  process  normally 

bra 

99$ 

/exit 

10$: 

jsr 

ShortKey 

/yes,  process  as  a  shortcut 

99$: 

rts 

/exit 

The  shortcut  key  handler  will  need  to  decide  what  to  do  based  on  the  key  that  was  pressed  Usually 
the  shortcut  bit  (bit  7)  will  be  removed,  the  character  will  then  be  converted  to  uppercase,  and  the 
resulting  character  code  will  be  used  to  search  through  a  table  of  valid  shortcut  keys.  If  the 
particular  shortcut  key  is  not  supported,  the  handler  just  returns,  ignoring  the  keypress.  If  the  key 
is  implemented,  the  handler  needs  to  call  an  appropriate  subroutine  to  process  the  shortcut  key: 
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/Shortcut  key  handler.  Call  with  keycode  in  A-register 
ShortKey : 

;Do  some  minor  conversion  on  the  keycode 
and  #-SHORTCUT 
cmp  # • a ' 

bit  10$ 
cmp  #'z'+l 
bge  10$ 
sec 

she  #('a'-»A') 


/lop  off  shortcut  bit 
/check  if  lowercase 
/branch  if  less  than  "a" 
/or  greater  than  "2" — ^ 


/it's  lowercase:  convert  to  upper 
/by  subtracting  the  ASCII  difference—^ 
/between  a  lowercase  'a'  and  an 
/uppercase  'A' 


10$: 

/Now  that  we  have  a  shortcut  key,  we  go  searching  through 

/a  table  of  valid  shortcut  keys,  looking  for  a  match.  Use  Y-reg 

/to  index  so  we  can  use  X-reg  later  for  CallRoutine. 


20$: 


Idy 

cmp 
beq 
dey 
bpl 


bmi 


#NUM__SHORTCUTS 

shortcuts, y 
30$ 

20$ 


99$ 


/start  at  top  of  table 

/check  for  a  keycode  match 
/branch  if  found 
/else,  try  next 
/loop  until  done.  NOTE:  must 
/not  have  more  than  127  shortcuts 
/or  this  branch  will  fail! 
/no  match,  ignore  this  key 


30$: 

/We've  found  a  match.  Get  the  corresponding  routine  address  from 

/the  Jump  table  and  call  the  routine 

Idx  h__shortCutTbl,  y  /get  high  address  of  routine 

Ida  l__shortCutTbl,  y  /and  low  address 

jsr  CallRoutine  /call  the  routine 


99$: 


rts 


/  exit 


/Table  of  shortcut  keys  and  their  corresponding  routines 


/Valid  shortcut  keys 

shortcuts: 

.byte 

•0' 

/I 

undo 

.byte 

1  fj*  t 

/2 

text 

.byte 

.p. 

/3 

print 

.byte 

«Q« 

/4 

quit 

.byte 

ijjt 

;5 

new  document 

.byte 

•G' 

/6 

goto  page 

.byte 

•B* 

/7 

boldface  toggle 

.byte 

•0' 

/8 

outline  toggle 

.byte 

'I' 

/9 

italic  toggle 

.byte 

•U' 

/lO 

underline  toggle 

.byte 

•D' 

/II 

delete 

.byte 

•c 

/12 

copy 

.byte 

•S' 

/13 

scroll 

.byte 

/14 

load  document 

NUM_SHORTCUTS 

ss=     { -k  _ 

shortcuts 

-  1)  /numbe 

.if  (NUM__SHORTCUTS 

>  127) 

.echo 

WARNING: 

too  many 

shortcuts 

.endif 


25 


Text,  Fonts,  and  Keyboard  Input 


; Table  of  low  bytes  of  shortcut  routine 
1  shortCutTbl: 


.byte 

[DoUndo  , 

'  1 

.  byte 

[DoText  , 

'  2 

.  byte 

luorrmt  , 

•  3 

•  byte 

lUOUUxt  , 

A 

H 

.  byte 

(DoNew  , 

'  5 

•  byte 

lL/0(jOt  0                                    ,  1 

»  c 
o 

.byte 

[DoBoldface  , 

7 

.byte 

[DoOutline  , 

8 

.byte 

[Doltalic 

9 

.byte 

(DoUnderline  , 

•10 

.byte 

IDoDelete  , 

•11 

.byte 

(DoCopy  , 

•12 

.byte 

[DoScroll  t 

•13 

.byte 

[DoLoad  t 

•14 

; Table  of  high  bytes  of  shortcut  routine 
h  ShortCutTbl: 


.byte 

] DoUndo 

;1 

.byte 

] DoText 

;2 

.byte 

IDoPrint 

;3 

.byte 

IDoQuit 

;4 

.byte 

] DoNew 

;5 

.byte 

]DoGoto 

;6 

.byte 

3  DoBoldface 

;7 

.byte 

]  DoOutline. 

;8 

.byte 

] Doltalic 

;9 

.byte 

] DoUnderline 

;io 

.byte 

] DoDelete 

;11 

.byte 

] DoCopy 

;12 

.byte 

] DoScroll 

;13 

.byte 

] DoLoad 

;14 

The  Text  Entry  Prompt 

Whenever  an  application  will  be  accepting  text  input,  it  is  a  good  idea  to  offer  a  prompt,  or  cursor, 
to  mark  the  point  at  which  text  will  appear.  GEOS  offers  three  routines  for  automatically 
configuring  sprite  #1  to  act  as  a  text  entry  prompt: 


•  InitTextPrompt 

Initialize  sprite  #1  for  use  as  a  text  prompt. 

•  PromptOn 

Turn  on  the  prompt  (show  the  text  cursor  on  the  screen). 

•  PromptOff 

Turn  off  the  prompt  (remove  the  text  cursor  from  the  screen). 

The  prompt  automatically  flashes  on  the  screen  without  disrupting  the  display  and  can  be  resized 
to  reflect  die  point  size  of  a  particular  font 
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Important:  Interrupts  should  always  be  disabled  and  alphaFlag  should  be  cleared  when 
PromptOff  is  called.  The  following  subroutine  illustrates  the  proper  use  of 
PromptOff: 

KillPrompt : 

php  /save  i  status 

sei  >  /disable  interrupts 

jsr    PromptOff  /prompt  «  off 

LoadB  alphaFlag,  #0 — ^lear  alpha  flag  ^ 

pip  /restore  i  status 

rts  /exit 


Sample  Keyboard  Entry  Routine 

As  an  example,  we  will  use  some  of  the  concepts  covered  in  this  chapter  in  real-world  code.  The 
following  routine  will  patch  into  key  Vector  and  output  text  as  keys  are  pressed: 


/***  CONSTANTS  *** 
TXT_LEFT  ==10 

TXT_RIGHT  ==   (SC_PIX_WIDTH  -  TXT_LEFT) 

TXT_TOP  ==20 

TXT__BOT  ==   (SC  PIX  HEIGHT  -  TXT  TOP) 


/text   (x,y)   starting  position 
TXT_X  ==20 
TXT_Y  ==50 

/size  of  the  text  buffer 
TXTBUFSIZE         ==  $200 


/text  left  margin 

/text  right  margin 

/text  top  margin 

/text  bottom  margin 


/1/2K  is  far  more  than  enough  for  ^ 
/now.  To  accept  multiple  lines, 
/the  buffer  will  need  to  grow 


/Characters  to  accept  before  buffer  overflow  fault 
MAX  CHARS  30 


if  0 

Start Text : 

Initializes  the  text  input  process  by  loading  the  proper 
vectors,  setting  flags,  etc.  Wedges  Keyin  into  keyVector  to 
intercept  keypresses  and  output  them  to  a  single  line. 

Pass:  nothing 

Returns:  text  input  routine  in  keyVector 

Destroys:  ? 

endif 


StartText: 

/Send  our  text  output  to  both  screens 

LoadB    textDispBufOn,#(ST_WR_FORE  |  ST  WR  BACK) 
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/Install  our  character  handler 

LoadW    keyVector, #KeyIn  /keypresses  vector  thru  here 

LoadW     stringFaultVec,#TextFault        /and  string  faults  here 

/Install  the  system  font  and  clear  all  text  attributes 
jsr  UseSystemFont- 
Ida  #PLAINTEXT 
jsr  PutChar 

/Set  the  left  and  right  margins 

LoadW     leftMargin, #TXT_LEFT 
LoadW  rightMargin,#TXT_RIGHT 

/Set  the  top  and  bottom  margins 
LoadW     windowTop, #TXT_TOP 
LoadW  windowBottom,TXT_BOT 

/Set  the  text  starting  position 
LoadW     stringX, #TXT_X 
LoadB     stringy,  #TXT__Y 

/Initialize  the  prompt 

Ida  currentHeight 
jsr  InitTextPrompt 
jsr  PromptOn 

/Point  at  the  start  of  the  line  buffer 

LoadW    txtBuf ,#bigTextBuffer  /where  to  start 

LoadB    txtBuf Index, #0  /index  from  start 

/Max  number  of  characters  to  accept 
LoadB     txtlnMax, #MAX_CHARS 

/And  where  control  goes  if  we  go  over... 
LoadW    bufFaultVec,#Buf Overflow 

/Turn  text  on  • 
LoadB    textOn, #TRUE 

/Exit 

rts 

.ramsect 

/Buffer  that  will  hold  all  the  text  we  enter.  We  let  the  key  input 
/routine  build  it  up  a  line  at  a  time  by  passing 

bigTextBuf fer:  .block  TXTBDFSIZE 

textDispBufOn:  .block  1  /holds  dispBufferOn  value  for  text 

txtlnMax:  .block  1  /number  of  characters  that  will 

/generate  buffer  overflow  fault 
textOn:  .block  1  /text  is  ON  flag.   (TRUE  «  ON) 

.if  ((*  &  $ff)        $ff)  /if  indirect  jump  vector  straddles  a  page 

.block  1  /boundary,  fix  it  to  compensate  for  a  bug 

.endif  /in  the  6502  architecture  ^ 
bufFaultVec       .block  2 

.psect 

★★*************************************************************** 

KeyIn: 

When  a  key  is  pressed,  control  comes  here  off  of  MainLoop 
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Keyin: 


10$: 
99$: 


Ida  menuNuiTiber 

bne  99$ 

Ida  keyData 

brr.i  10$ 

jsr  Norrr.alKey 

bra  99$ 

jsr  ShortKey 

rts 


; check  current  menu  level 
/ignore  keys  while  menus  down 
;get  the  keypress 
;w'as  it  a  shortcut? 
/no,  process  normally 
/exit 

/yes,  process  as  a  shortcut 
/exit 


/ShortKey: 

/Control  comes  here  when  shortcut  keys  are  pressed 


ShortKey: 
rts 


/no  shortcut  key  handler  now.  just  ignore  keypress. 


.**★*★«********«*★****«★**«♦«**** *«******************************* 

/NormalKey : 

/Control  comes  here  when  non-shortcut  keys  are  pressed 


SPACE 
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NormalKey: 

/Return  immediately  if  text  is  off 
Ida  textOn 


bne 
rts 


5$ 


/branch  if  text  on 


5$: 


jsr 


KillPrompt 


/turn  the  prompt  off 


/Save  the  current  value  of  dispBufferOn  and  load  up  the  correct 
/value  for  text  output. 

PushB  dispBufferOn 

MoveB    textDispBuf On, dispBufferOn 


/Load  the  current  cursor  position  into  the  PutChar  position 
/registers,   just  in  case  we  need  to  use  them  later. 


MoveW  stringX,rll 

Ida  stringY 
clc 

adc  baselineOf f set 

sta  rlH 


/X  printing  position 
/convert  y  cursor  position  to 
/baseline  position 

/y  printing  position 


/Process  the  character 

Ida  keyData 
cmp  #SPACE 
bge        4  0$ 


/get  the  keypress  again 

/cmp  with  first  printable  char 

/branch  if  printable 


/Check  the  control  character  against  a  table  of  special  action 
/keys.  Use  Y-reg  to  index  so  we  can  use  X-reg  later  for 
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;CallRoutine . 
Idy 

20$: 

cmp 
beq 
dey  • 
bpl 


bmi 


#NUM_CTRL  ;  start  at  top  of  table 

i 

ctrlKeys,y  /check  for  a  keycode  match 

30$  ;branch  if  key  matches  table  entry 

;else,  try  next ' 
20$  ;loop  until  done.  NOTE:  must  not 

./have  more  than  127  special  keys 

/or  this  branch  will  fail! 
88$  /no  match  was  found,  ignore  this  key 


30$: 

/We've  found  a  match  on  a 
/routine  address  from  the 
Idx  .  h__CtrlTbl,y 
Ida  l_CtrlTbl,y 
jsr  CallRoutine 
bra  88$ 

4  0$: 

/It's  a  normal  alphanumeric 
/screen  and  save  it  in  the  t 
pha 


control  character.  Get  the  corresponding 
jump  table  and  call  the  routine 

/get  high  address  of  routine 
/and  low  address 
/call  the  routine 
/go  clean  up  and  exit 


Idy 
sta 
iny 
Ida 
sta 
sty 
pla 


Dsr 

MoveW 

Ida 

cmp 

bit 

Ida 

Idx 

jsr 

88$: 

/Clean  up 
Ida 
beq 
jsr 


txtBuf Index 
(txtBuf ) ,y 

#NULL 
(txtBuf) ,y 
txtBuf Index 


99$: 


PopB 
rts 


PutChar 
rll, stringX 
txtBuf Index 
txtlnMax 
88$ 

bufFaultVec 

bufFaultVec+1 

CallRoutine 


textOn 
99$ 

Prompt On 


dispBuf ferOn 


character.  Output  it  to  the 
ext  buffer 

save  the  character  code 
pointer  into  current  text  buffer 
place  the  character  into  the  buffer 
point  to  next  position  in  buffer 
and  null-terminate  the  string 

set  down  the  new  index  value 
get  the  character  code  back.  (Note: 
we  could  have  pulled  it  off  of 
keyData,  but  future  versions  may 
pre-process  or  translate  the  char 
code  in  the  A-reg  before  passing) 
print  it  on  the  screen 
update  the  prompt  X-position 
was  that  the  last  character  we 
can  accept? 
OK  if  under  max. 
otherwise,  call  buffer  overflow 
routine 


/only  re-enable  the  prompt  if  text 
/is  still  on  (might  have  changed!) 
/turn  the  prompt  back  on 


/restore  dispBufferOn 
/  Exit 


Table  of  control  keys  and  their  corresponding  routines 


/Valid  control  keys 

ctrlKeys : 

.byte  CR 
.byte  BACKSPACE 
.byte  KEY_DELETE 
.-byte     KEY  INSERT 


1  Carriage  return 

2  backspace 

3  ditto 

4  ditto 
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.byte     KEY__RIGKT  ;5  ditto 

NUM_CTRL  ==  (*  -  ctrlKeys  -  1)  ; number  of  control  keys 

.if  (NUM__CTRL  >  127) 

.echo     WARNING:  too  many  control  keys 

.encif 

; Table  of  low  bytes  of  control  key  routine  addresses 


l_CtrlTbl: 

.byte     [DoReturn  ;1 

.byte  ' '  (DoBackSpace  ;2 

.byte     [DoBackSpace  ;3 

.byte     (DoBackSpace  ;4 

.byte     [DoBackSpace  ;5 


; Table  of  high  bytes  of  control  key  routine  addresses 
h__CtrlTbl: 

.byte     ] DoReturn 

.byte     ] DoBackSpace 

.byte     ] DoBackSpace 

.byte     ) DoBackSpace 

.byte     ) DoBackSpace 

;  Exit 

rts 

. ramsect 
tempDisp:  .block  1 

sysKeySave:        .block  2 

.psect 

.**«««**«★***★***★★★★★*★**★★★★★★******★★****«********************* 

;KillPrompt: 

/Proper  way  to  use  PromptOff.  Disable  interrupts  and 

/clears  alphaFlag.  • 

t 


KillPrompt : 

php  /save  i  status 

sei  /disable  interrupts 

jsr  PromptOff  /prompt  «  off 

LoadB  alphaFlag, #0  /clear  alpha  flag 

pip  /restore  i  status 

rts  /exit 


/DoReturn: 

/Process  a  carriage  return 
J 

.★***«*****★★****★★★*★**★*★*********★*★*****★*******★***★★ 

DoReturn : 

/No  real  carriage  return  handler,  yet.  Just  shut  text  off 
LoadB    textOn, #FALSE  / 

rts  /    .        .  . 

.*******★*********★*★★★****★*****«*******★***********★*★*★★*** 

/DoBackSpace: 
» 

/Process  a-  backspace 


/temporary  hold  for  dispBufferOn 
/holds  address  of  system  key  routine 
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DoDoBackspace: 


Idy 

txtBuf Index 

;get  ptr  into  current  text  buffer 

beq 

99$ 

;if  no  characters  in  buffer,  exit 

dey 

/back  up  a  character 

sty 

txtBuf Index 

7  and  make  the  new  index  permanent 

Ida 

(txtBuf ) ,y 

;get  the  character  we  want  to  delete 

jsr 

EraseCharacter 

/and  remove  it  from  the  screen 

Idy 

txtBuf Index 

/get  the  index  to  the  character  we 

Ida 

#NULL 

/we  just  deleted  and  make  it  the 

sta 

(txtBuf ),y 

/ null-terminator 

MoveW 

rll, stringX 

/update  the  cursor's  x-position 

rts 

/exit 

'k**'kit*ie**'k-kitit'k1r-teicie-te1e*ieieif*ie1eieieie*ic1iitirieielrieicie*** 

EraseCharacter: 


Physically  remove  a  character  from 

.if  (C64  II  C128)  /This  routine 
EraseCharacter : 


10$: 


.endif 


MoveW 

rll,r4 

Idx 

currentMode 

jsr 

GetRealSize 

sta 

r3L 

Ida 

rlH 

sec 

sbc 

r3L 

sta 

r2L 

txa 

clc 

adc 

r2L 

sta 

r2H 

sty 

r3L 

sec 

sbc 

rllL 

sta 

r3L 

Idy 

rllH 

bcs 

10$ 

dey 

sty 

r3H 

jsr 

Rectangle 

rts 

the  screen 

is  in  the  Apple  GEOS  jump  table 

/current  X  is  rectangle's  right  edge 

/get  the  mode  we're  in 

/go  calc  the  size  of  the  character 

/set  down  baseline  offset 

/calc  top  of  character  by  subtracting 

/baseline  offset  from  y-position 

/and  making  top  edge  of  rectangle 
/add  char  height  to  top  edge 
/to  calc  bottom  edge 

/and  make  bottom  of  rectangle 

/set  down  width  so  we  can  subtract  it 

/from  the  current  x-position  to 

/find  the  character's  starting 

/position 

/subtract  one  from  hi  if  borrow 


/make  left  edge  of  rectangle 
/erase  in  current  pattern 
/exit 


Buf Over flow: 

What  to  do  if  the  buffer  hits  its  maximum. 


BufOverflow: 

/No  real  overflow  handler,  yet.  Just  shut  text  off 
LoadB    textOn,#FALSE  / 
rts 


/Text Fault: 
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; string  faults  come  here. 

************************************************** 

TextFault : 

/No  real  text  fault  handler,  yet.  Just  shut  text  off 
LoadB    textOn, #FALSE 

rts  ; 
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MainLoop  and  Interrupt  Level:  a 
Technical  Breakdown 

The  GEOS  Kemal  operates  on  two  distinct  levels:  MainLoop  Level  and  Interrupt  Level.  MainLoop 
Level  is  characterized  by  the  GEOS  MainLoop  —  a  never-ending  loop  at  the  heart  of  GEOS  that 
routes  events  to  the  application.  Whenever  the  application  does  not  have  control,  MainLoop 
usually  does. 

But  there  is  also  Interrupt  Level.  Periodically  (usually  every  l/60th  of  a  second)  the  computer 
hardware  temporarily  interrupts  the  microprocessor.  The  processor  may  be  in  the  middle  of 
MainLoop,  deep  within  a  GEOS  routine,  or  somewhere  in  the  applcation.  Either  way,  the  6502 
immediately  suspends  whatever  it  is  doing  and  passes  control  to  the  GEOS  Interrupt  Level. 
Interrupt  Level  scans  the  keyboard  circuitry,  moves  the  mouse  pointer,  flashes  the  text  prompt, 
decrements  timers,  and  performs  other  low-level  tasks.  Interrupt  Level  operates  independently  of 
MainLoop  and  ensures  that  certain  things  get  done  on  a  regular  basis.  When  the  Interrupt  Level 
processing  is  complete,  control  returns  to  the  point  where  the  original  interrupt  occurred. 

Whatever  GEOS  does  at  Interrupt  Level  is  mostly  transparent  to  the  application.  Only  when  an 
application  strays  from  the  beaten  path  will  it  need  to  worry  about  the  specifics  of  Interrupt  Level 
processing. 

This  is  a  technical  discussion  of  MainLoop  and  Interrupt  Level.  For  a  more  general 
discussion,  refer  to  Chapter  @GEOSAPPS@. 

MainLoop  Level 

When  GEOS  starts  an  application,  it  first  initializes  the  operating  system  and  then  jsr's  to  the 
application's  start  address.  The  application  is  expected  to  perform  its  basic  startup  procedures, 
such  as  initializing  its  menus,  icons,  and  processes,  and  the  return  immediately  with  an  rts.  This 
rts  will  place  GEOS  at  the  beginning  of  MainLoop.  MainLoop  is  primarily  a  small,  endless 
loop  of  function  calls: 

MainLoop  Service  Routines 

MainLoop  itself  is  rather  short.  The  meat  of  its  function  is  hidden  in  the  various  service  routines 
that  it  calls.  Because  these  service  routines  interact  direcdy  with  the  application,  it  is  useful  to 
understand  the  specific  conditions  that  affect  their  operation.  The  pseudo-code  diagrams  at  the  end 
of  this  chapter  illustrate  the  operation  of  the  more  important  service  routines. 

Patching  Into  MainLoop 

Although  most  applications  can  function  entirely  off  of  events,  some  may  find  the  need  to  install 
their  own  service  routine  direcdy  off  of  MainLoop.  GEOS  has  a  single  vector  for  tiiis  purpose: 
appIicationMain,  which  usually  contains  $0000  and  is  therefore  unused.  By  placing  a  routine 
address  into  this  vector,  GEOS  will  call  through  tiiis  vector  every  pass  through  MainLoop.  To 
remove  tills  call,  tfie  application  can  again  store  $0000  into  the  vector. 
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The  Basics  of  Interrupt  Level 

Interrupt  Level  is  primarily  responsible  for  maintaining  the  interactive  and  time-based  apsects  of 
GEOS.  Interrupt  Level  updates  the  mouse  state  and  the  mouse  cursor  position,  watches  for  double- 
clicks, decrements  process  and  sleep  timers,  gets  keyboard  input,  flashes  the  prompt,  and 
generates  a  new  random  number  every  vblank,  among  other  (more  obscure)  tasks. 

The  Vertical  Blank  Interrupt 

The  Interrupt  Level  interrupt  is  tied  directly  to  the  video  circuitry.  In  order  to  keep  the  screen 
phosphors  glowing,  the  image  must  be  redrawn,  or  refreshed,  many  times  per  second.  Each 
complete  coverage  of  the  picture  tube  is  called  2i  frame,  and  the  rate  at  which  frames  are  drawn  is 
cailtdthtframe  rate  or  refresh  rate. 

At  the  end  of  each  frame,  the  electron  beam  is  switched  off  and  returned  to  the  upper  left  comer  of 
the  picture  tube  to  begin  drawing  again.  This  period  when  the  beam  is  off  is  called  the  vertical 
blank,  or  vblank.  Every  vblank,  the  IRQ  (Interrupt  ReQuest)  line  on  the  6502  is  pulled  low.  If  the 
interrupt  disable  bit  in  the  status  register  is  clear  (asit  usually  should  be),  an  interrupt  is  generated. 
This  interrupt  is  often  called  the  vblank  interrupt. ^EOS  uses  the  vblank  interrupt  as  the  basis  for 
its  Interrupt  Level  processing. 

The  vblank  interrupt,  along  with  the  scanning  of  the  video  frame,  occurs  in  a  precisely  timed 
sequence:  60  times  per  second  on  NTSC  monitors  (the  United  States  standard)  and  50  times  per 
second  on  PAL  monitors  (the  European  standard).The  GEOS  FRAME^RATE  constant  reflects 
the  number  of  frames  per  second  (either  50  or  60)  depending  on  the  state  of  the  PAL  and  NTSC 
constants. 

How  to  Disable  Interrupts 

Because  the  vblank  interupt  is  an  IRQ  (Interrupt  ReQuest),  the  6502  has  the  option  of  ingoring  the 
request.  To  disable  IRQ  interrupts,  an  application  need  only  set  the  interrupt  disable  bit  in  the 
6502*s  status  register  using  the  sei  (SEt  Interrupt  disable  bit)  instruction.  Because  GEOS  depends 
on  Interrupt  Level  executing  on  a  timely  basis,  an  application  should  disable  interrupts  only  when 
absolutely  needs  to  and  then  only  for  short  periods  of  time.  If  an  interupt  occurs  while  the 
interrupt-disable  bit  is  set,  the  interrupt  will  not  be  serviced.  If  too  many  interrupts  are  missed, 
much  of  the  real-time  features  of  GEdS  —  the  mouse  pointer,  processes,  double  click  detection, 
etc.  —  will  become  sluggish. 

In  conventional  6502  programming,  it  is  standard  practice  to  surround  blocks  of  interupt-sensitive 
code  with  an  sei-cli  sequence:  an  initial  sei  to  disable  interrupts  and  an  ending  cli  to  reenable 
interrupts.  This,  however,  is  not  a  totally  safe  practice  because  the  cli  always  reenables  interrupts 
regardless  of  their  original  state.  If  interrupts  were  originally  disabled,  the  cli  may  inadvertently 
reenable  them.  As  applications  get  large,  it  becomes  easier  to  embed  these  interrupt  disable/enable 
sequences  deep  within  subroutines.  If  one  subroutine  disables  interrupts  then  calls  another 
subroutine  that  then  performs  a  cli  (returning  with  interrupts  enabled  when  they  shouldn't  be),  the 
results  may  be  a  disasterous  bug. 

It  is  good  to  practice  a  littie  defensive  coding  and  get  into  the  habit  of  saving  the  interupt  status 
when  disabling  them  around  blocks  of  code.  The  following  sequence  works  well: 

php  ;save  current  interrupt  disable  status 

sei  /disable  interupts 

; (interrupt-sensitive  code  goes  here) 
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pip 


/restore  old  interrupt  status 


This  php-sei-pip  method  will  save,  set,  and  then  restore  the  interrupt  disable  bit.  This  way 
interrupts  won't  be  inadvertently  reenabled  when  they're  expected  to  be  disabled. 

Apple  GEOS  Interrupts 

Unlike  the  Commodore  computers,  the  Apple  He  does  not  generate  its  own  vblank  IRQ  interrupts. 
This  function  is  usually  provided  by  external  hardware  plugged  into  slot  7:  the  Apple  mouse  card 
or  the  Berkeley  Softworks  IRQ  Management  Card.  If  neither  of  these  devices  is  present  and  there 
is  no  other  interrupt  source,  Apple  GEOS  will  generate  software  interrupts. 

Apple  Software  Interrupts 

GEOS  may  occasionally  be  run  on  systems  with  no  interrupt  source.  This  is  an  unfortunate 
situation  because  GEOS  depends  heavily  on  interrupt  processing.  GEOS  will  recognize  this 
configuration  and  generate  software  interrupts  during  MainLoop  by  calling  IrqMiddle.  With 
applications  that  don't  have  time-consuming  event  routines  hanging  off  of  MainLoop,  Interrupt 
L^vel  processing  will  occur  often  enough  to  make  the  system  usable.  If  system  degradation  is  too 
great,  an  application  can  simulate  its  own  software  interrupts  as  necessary.  For  more  information, 
refer  to  IrqMiddle  in  the  Routine  Reference  Section. 

Example: 


DoSoftlnts 

Description:    Simulate  vblank  interrupts  under  Apple  GEOS  when  no  interrupt  source  is 
present. 

Pass:  nothing 

Destroys:  a,x,y 


DoSoftlnts: 
bit 
bne 
php 
sei 
Jsr 
pip 

10$: 


intSource 
10$ 


IrqMiddle 


; check  interrupt  source 
;exit  if  hardware  interrupt  source 
;else,  generate  soft  interrupt 
/disable  interrupts  (just  in  case) 
/software  interrupt  now! 
/restore  old  interrupt  status 


The  Apple  GEOS  Interrupt  Management  Card 

The  Berkeley  Softworks  JRQfManagement  card  requires  reenabling  after  every  interrupt  in  order  to 
generate  next  interrupt.  Part  of  the  Apple  Interrupt  Level  processing  reenables  the  IRQ  Genei  aioi^ 
card  to  interrupt  on  the  next  vblank.  Normally  this  will  keep  interrupts  triggering  on  a  regular 
basis. 


^miSrd^r 


However,  if  the«Q44anagemem^ard  generates  an  interupt  while  the  6502  interrupt  disable  bit  is 
set,  the  interrupt  service  routine  will  not  run,  and  the  IRQ  Management  card  will  never  be 
reenabled  for  the  next  interrupt 
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Apple  GEOS  attempts  to  keep  interrupts  running  by  reenabling  the  IRQ  Management  card  during 
MainLoop  and  whenever  a  call  through  the  jump  table  switches  banks.  Normally  applications 
will  do  this  often  enough  in  their  normal  operation  to  reenable  the  IRQ  Management  card  ron  a 
regular  basis.  It  is  conceivable,  however,  that  in  some  very  odd  cases  neither  of  these 
circumstances  will  occur  often  enough  (very  odd  cases,  indeed —  if  an  application  is  both  disabling 
interrupts  and  not  going  back  to  MainLoop,  there  is  probably  something  fundamentally  wrong 
with  the  structure  of  the  program).  An  application  can  reenable  the  IRQ  Management  cardwhen 
necessary  with  the  following  sequence: 

bit  intSource 

bvc  5$ 

St  a  IRQ__GEN 

5$: 


; check  the  interrupt  source 
/ignore  if  not  BSW  card  IRQ  Manager 
/otherwise,  trigger  IRQ  Manager 
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The  vblank  interrupt  service  routine  is  one  of  the  most  complex  aspects  of  GEOS.  Fortunately, 
most  applications  will  need  to  know  little  more  about  the  Interupt  Level  process  than  its  basic 
functionioning.  However,  there  are  some  unavoidable  conflicts  between  Interupt  Level  and 
normal,  mainstream  processing,  and  these  are  important  to  know. 

Two-byte  Variables 

During  non-interrupt  level  processing,  it  is  important  to  disable  interrupts  before  referencing  a 
word  value  that  might  get  changed  at  Interrupt  Level  or  changing  a  word  value  that  might  get 
referenced  at  Interupt  Level.  A  two-byte  quantity  requires  two  memory  accesses,  and  there  is  a 
small  chance  that  an  interrupt  may  occur  after  the  first  byte  has  been  accessed  but  before  the  second 
byte  has  been  accessed.  This  can  result  in  a  situation  where  a  word  value  has  the  high-byte  of  one 
number  and  the  low- byte  of  another.  Take  for  example  the  variable  mouseXPos,  which  is 
modified  at  Interrupt  Level.  The  seemingly  innocent  code  fragment  below  illustrates  the  problem: 

MoveW    mouseXPos, oldX  /update  our  old  mouse  x-position  with  current  mouse  x 

Which  exands  to  the  following  at  assembly  time: 

Ida        mouseXPos  /update  our  old  mouse  x-position  with  current  mouse 

sta  oldX 

Ida  mouseXPos+1 

sta  oldX+1 

If  an  interrupt  occurs  between  the  Ida  mouseXPos  and  the  subsequent  Ida  mouseXPos+1, 
the  result  word  result  stored  in  oldX  may  be  entirely  wrong.  The  solution  is  to  temporarily  disable 
interrupts  around  the  access: 

php  ; disable  interrupts  around  access 

sei  ; 

MoveW  mouseXPos, oldX  /update  our  old  mouse  x-position  with  current  mouse  x 

pip  ; restore  old  interrupt  status 

Be  aware,  though,  that  the  php-sei-pip  sequence  has  its  own  set  of  ideosyncracies:  the  pip 
restores  the  entire  status  register,  not  just  the  interrupt  disable  bit,  thereby  overwriting  any  new 
condition  codes.  Therefore,  disabling  as  in 

php  ; disable  interrupts  around  compare 

sei  ; 
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CmpW      mouseXPos, oldX  /compare  current  X  with  Old  X 

pip  '/restore  interrupts 

would  defeat  the  whole  purpose  of  the  CmpW.  In  such  cases,  the  condition  codes  can,  of  course, 
be  tested  before  the  pip.  A  better  solution,  however,  would  disable  interrupts,  shadow  the  word 
value  to  a  temporary  variable,  restore  the  interrupt  disable  status,  then  do  all  checking  against  this 
temporary  value,  which  won't  get  changed  by  Interrupt  Level. 

Example: 


/Check  if  mouse  is  within  the  left  and  right  text  margin 
IsMselnMargins: 


10$: 

20$: 
99$: 


php 
sei 

MoveW  mouseXPos,rO 
pip 


CmpW 
bge 
Ida 
beq 

CmpW 
ble 
Ida 
beq 

Ida 

rts 


rO, leftMargin 
10$ 

#FALSE 
99$ 

rO, rightMargin 

20$: 

#FALSE 

99$ 

#TRUE 


disable  interrupts  around  mouseXPos  access 
and  copy  current  pos  to  a  working  location 

restore  interrupts 


/check  left  margin 
/branch  if  inside  left 
/else,   flag  fault 
/branch  always  to  exit 

/check  right  margin 
/branch  if  inside  right 
/else,  flag  fault 
/branch  always  to  exit 

/no  fault  (inside  text  margins) 

/exit 


Word  variables  to  be  careful  with  include  mouseXPos,  mouseLeft,  mouseRight, 
intTop Vector,  and  intBot Vector,  all  of  which  are  either  read  or  written  to  by  Interrupt  level. 


The  Decimal  Mode  Flag 

GEOS  adopts  the  convention  that  the  normal  operating  state  of  the  computer  has  decimal  mode 
disabled.  Any  routine  that  enables  decimal  mode  must  also  disable  it  Versions  of  GEOS  64  prior 
to  V  1.2  do  not  disable  decimal  mode  during  interrupt  level  processing.  If  operating  under  one  of 
these  versions,  it  is  necessary  to  disable  intemipts  prior  to  using  the  decimal  mode  flag. 


Patching  Into  Interrupt  Level 

Very  few  applications  will  need  access  to  the  system  at  Interrupt  Level.  Most  tasks  that  would 
traditionally  require  the  use  of  a  time-based  interrupt  can  be  handled  deftly  enough  with  GEOS 
processes.  If  an  application  can  drive  itself  entirely  off  of  MainLoop  events,  it  should.  The  world 
of  Interrupt  Level  is  a  delicate  one;  it  is  very  easy  to  disrupt  the  entire  system  by  doing  the  wrong 
thing  during  Interrupt  Level.  With  that  said,  though,  GEOS  provides  two  vectors  that  allow  an 
application  that  knows  what  it's  doing  to  tap  directly  into  Interrupt  Level:  intTopVector  and 
intBotVector. 

As  illustrated  in  the  Interrupt  Level  pseudo-code  at  the  end  of  this  chapter,  control  passes  through 
these  two  vectors  at  different  points  in  the  intermipt  process.  intTopVector  allows  the 
application  to  patch  in  before  most  of  the  Interrupt  Level  processing  has  occurred  and 
intBotVector  allows  the  application  to  patch  in  after  most  of  the  Interrupt  Level  processing  has 
occurred. 
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Important:    The  application  should  always  disable  interrupts  before  loading  a  new  address  into 
either  intTopVector  or  intBot Vector.  The  program  will  very  likely  crash  if  this 
 precaution  is  not  taken.  


( 


System  Use  of  intTopVector  and  intBotVector 

GEOS  64  and  GEOS  128  use  intTopVector  to  point  to  InterruptMain,  a  vital  function  of  the 
Commodore  GEOS  Interrupt  Level,  whereas  Apple  GEOS  does  not  use  either  of  these  vectors. 
The  application  can  use  either  intTopVector  or  intBotVector  under  Apple  GEOS  without  any 
worry.  However,  under  Commodore  GEOS,  an  application  that  uses  intTopVector  should  call 
the  address  that  was  originally  in  intTopVector  when  it  is  done.This  will  ensure  that  the 
Commodore  GEOS  InterruptMain  will  be  executed  properly. 

Example: 

; Install  our  interrupt  routine  into  intTopVector 
Installint : 

php  /disable  interrupts 

sei 

MoveW    intTopVector, oldTopVector        ;save  address  of  current  routine 
LoadW    intTopVector, #MyIntRout  /install  our  interrupt  routine 

pip  /restore  interrupts 

rts 

/Remove  our  interrupt  routine  from  intTopVector,  replacing  it  with  old. 
Removeint 

php  /disable  interrupts 

sei 

MoveW    oldTopVect or, intTopVector       /restore  old  routine 
pip  /restore  interrupts 

rts 


/My  interrupt  service  routine 
MylntRout : 

Ida  OldTopVect or 

Idx  oldTopVector+1 
jmp  CallRoutine 


/nothing  to  do  yet... 
/exit  by  vectoring  through 
/old  interrupt  routine 
/let  it  rts. . . 


Guidlines  for  Interrupt  Level  Routines 

There  are  a  few  general  guidelines  for  any  routine  that  patches  into  Interrupt  Level: 

•  Keep  the  routines  short  Interrupt  level  is  not  the  place  for  time-consuming  code. 

•  Stay  away  from  GEOS.  Some  routines  will  work  correctly  at  interrupt  level  and  other 
won't.  Even  worse,  the  ones  that  won't  work  might  only  show  this  trait  after  your 
product  has  been  released  and  in  the  hands  of  users  for  months.  (It  is  O.K.,  though,  to 
use  CallRoutine,  as  many  of  the  examples  in  this  chapter  illustrate.) 

•  Never  clear  the  interrupt  disable  bit 

Following  these  guidelines  will  keep  your  Interrupt  Level  routines  as  innocuous  as  possible. 
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Interrupt  Level  Pseudo-Code 

The  following  pseudo-code  diagrams  illustrate  the  general  Interrupt  Level  constructs  in  each  of  the 
three  systems  (GEOS  64,  GEOS  128,  Apple  GEOS).  This  information  can  be  crucial  when  trying 
to  track  down  a  subtle  interaction  between  the  various  levels  of  GEOS. 

GEOS  64  and  GEOS  128  Interrupt  Level  

CBMInterruptLevel: 
{ 

/  •  Context  Save: 

Save  out  any  information  about  the  system  configuration  that  we  might  destroy  V 
Save6502Regs();  r  save  the  status  of  the  A.  X,  Y.  and  S  registers  V 

SaveGEOSRegsQ;  /*  save  r0-r15  and  a  few  internal  variables*/ 

SaveCBMState();  /*  save  state  of  Commodore  memory  banks  V 

SetlOInO;  /*  set  RAM  1  and  I/O  registers  in.  Much  of  Kernal 

is  now  inaccessibieV 

DblClicksO;  T  decrement  dblClickCount  if  non-zero  V 

if  (GEOS128) 

{     DoMouse();  r  GEOS  128  updates  mouse  here  V 

DoSetMouseO;  /*and  also  calls  SetMouse  in  mouse  driver.  SetMouse 

doesn't  exists  in  GEOS  64  input  drivers.*/ 

} 

DoKeyboardO;  r  scan  the  keyboard  and  add  a  char  to  the  queue  if  key  pressed  V 

DoAlarmSndO;  r  update  timer  for  alarm  sound  duration  */ 

/  *  Application  can  patch  into  the  following  two  vectors.  The  application's  routine  should 
always  end  by  indirectly  calling  the  routine  whose  address  was  originally  installed  in 
the  vector.  Use  CallRoutine  in  the  Kernal  (it's  bank  is  in)  in  case  the  pointer  is  $0000. 
*  / 

Calllndirect(intTopVector)  /*  call  indirectly  through  intTopVector.  On  the  C64/128,  this 

points  to  InterruptMain.  */ 
Calllndirect(intBotVector)  /*  call  indirectly  through  intBotVector.  This  is  usually 

$0000,  which  Calllndirect  ignores.  */ 

/*  Context  Res^re:  S>^i//?/D 
AP5/t>^<:©avB  otrt-atTyinformation  about  the  system  configuration  that  we^might  dootfof^/ 


RestoreCBMStateO 
RestoreGEOSRegsO 
Restore6502Regs() 


r  put  memory  banks  back  as  they  were  */ 

r  restore  r0-r15,  etc.*/ 

r  restore  A,  X,  Y,  and  S  registers  */ 

ReturnFromlRQO;  T  pick  up  where  we  left  off  */ 

) 
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GEOS  64  and  GEOS  128  interruptMain 


InteruptMain: 

Called  through  intTopVector  under  GEOS  64/128.  This  is  *VERY*  different  from 
InterruptMain  under  Apple  GEOS! 


InterruptMain: 
{ 

if  (GEOS64) 
{  DoMouseQ; 
} 

UpdateProcessesO; 

UpdateSleepsO; 

UpdatePromptO; 

GetNewRandomO; 

ReturnO; 


/  *  GEOS  64  updates  mouse  here  */ 

/  *  Update  the  process  timers  */ 

/  •  Update  the  sleep  timers  */ 

/  •  Flash/Update  the  text  prompt  V 

/  *  jsr  GetRandom  in  Kernal  V 
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Apple  GEOS  Interrupt  Level  

ApplelnterruptLevel: 
{ 

/  *  Context  Save: 

Save  out  any  information  about  the  system  configuration  that  we  might  destroy  V 
Save6502Regs();  /*  save  the  status  of  the  A,  X,  Y,  and  S  registers  V 

SaveAppleStateO;  r  save  state  of  Apple  memory  banks  V 

/*  Set  memory  configuration  to  normal/default  state  V 

RamReadOffO; 

RamWriteOffO; 

Page20ff(); 

AltZPOffO; 

IrqMiddleO;  I*  main  IRQ  processing  V 

/  *  Context  Restore: 

Save  out  any  information  about  the  system  configuration  that  we  might  destroy  V 

Restore AppleStateO;        /*  put  memory  banks  back  as  they  were  V 

Restore6502Regs();  /*  restore  A.  X,  Y.  and  S  registers  V 

ReturnFromlRQO;  /*  pick  up  where  we  left  off  V 
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Apple  GEOS  IrqMiddle  


IrqMiddle  (APPLE  VERSION). 

This  is  *VERY*  different  from  InterruptMain  under  CBM  GEOS! 
This  is  where  software  generated  interrupts  are  sent. 

*  / 

IntorruptMaio: 
{ 

SaveGEOSRegsO;  /*  save  r0-r15  and  a  few  internal  variables*/ 

/  *  Application  can  patch  into  the  following  vector  to  get  control  before  most  of  the 

Interrupt  Level  processing  has  occurred.  */ 
Calllndirect(intTopVector)  /*  call  indirectly  through  intTopVector.  On  the  Apple  this 

defaults  to  $0000,  which  Calllndirect  ignores  V 

/  *  Apple  GEOS  draws  the  mouse  cursor  (soft  sprite  #0)  at  interrupt  level  so  that  it  can 
minimize  flicker  by  avoiding  the  raster  beam.  However,  because  diffent  interrupt 
sources  (mouse  vs.  BSW  IRQ  Generator)  pull  the  IRQ  line  low  at  different  times  in  the 
Vblank  sequence,  the  sprite  is  either  drawn  earlier  or  later  depending  on  its  position 
on  the  screen.  */ 

if    (intSource  !=  BSWIRQ)       /*  if  the  BSW  IRQ  card  generated  the  interrupt...  V 
{     i  f   (mouseYPos  <  40)        ^  if  mouse  is  at  the  top  of  the  screen...  V 
{    doMouseLater  =  TRUE   /*  then  avoid  the  beam  by  drawing  it  later  V 

} 

else 

{    AppleSoftMouseServiceO;       /*  else,  draw  it  now.V 
} 

} 

DblClicksO;  /*  decrement  dblClickCount  if  non-zero  V 

DoMouseO;  /  *  update  mouse  now  V 

/  •  Turn  on  aux.  memory  and  give  the  clock  driver  control  V 

RamReadOnO;  /*  switch  auxiliary  memory  in  V 
RamWrtOnO; 

ReadClocklntO;  ^  call  to  aux.  memory  jump  table  for  clock  driver  V 

RamReadOff();  r  put  main  memory  back  in^  V 

RamWrtOffO; 

DoKeyboardO;  /*  scan  the  keyboard  and  add  a  char  to  the  queue  if  key  pressed  V 
UpdateProcessesO;  /  *  Update  the  process  timers  V 

UpdateSleepsO;  /  *  Update  the  sleep  timers  V 

UpdatePromptO;  /  *  Flash/Update  the  text  prompt  V 

GetNewRandomO;  /  *  jsr  GetRandom  in  Kernal  V 

/  *  Call  the  auxiliary  device  driver  interrupt  code*/ 
AuxDIntO; 

/  *  Application  can  patch  into  the  following  vector  to  get  control  after  most  of  the 
Interrupt  Level  processing  has  occurred.  */ 
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Calllndirect(intBotVector)  /*  call  indirectly  through  intBotVector.  This  is  usually 

$0000,  which  Calllndirect  ignores.  V 

/*  if  the  BSW  IRQ  card  generated  the  interrupt  and  we  haven't  done  the  mouse  yet...  V 

if    ({intSource      BSWIRQ)  &&  (doMouseLater  ==  TRUE)) 

{    AppleSoftMouseServiceO;       r  then  draw  the  mouse  now  V 

) 

RestoreGEOSRegsQ;  /*  restore  r0-r15,  etc.  V 

ReturnO; 

} 
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UpdateProcesses   


UpdateProcesses: 
{ 

if  (numProcesses  >  0)  /  *  Only' do  this  if  there  are  processes  in  the  table  V 
{ 

for  (EachProcess)  /*  go  through  each  process  in  the  table  V 

{ 

if  (Process  !=  FROZEN)       /*  only  if  unfrozen...  V 
{    DecrementTimer();  I*  count  down  one  tick  V 

if  (Timer  ==0)  T  if  timer  timed-out 

{     Process  =  RUNABLE;  /*  make  it  runable  V 

ResetTimerO;  /*  and  reset  the  counter  */ 

} 

} 

} 

} 

ReturnO; 

} 

UpdateSleeps  

UpdateSleeps: 
{ 

if  (numSleeping  >  0)  /  *  Only  do  this  if  there  routines  are  sleeping  */ 

{ 

for  (EachSleeping)       /*  go  through  each  sleeping  routine  */ 
{  . 

if  (SleepTimer  /*  if  counter  not  zero,  then  still  asleep!  */ 

{     Decrement  ;         ;  /*  so  count  down  one  tick  V 

} 

} 

} 

} 
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UpdatePrompt  

UpdatePrompt: 
{ 

if  (alphaFlag(BIT7)  ==1)  /  *  prompt  enabled  if  hi-bit  of  alphaFlag  set  */ 

{ 

Decrement AlphaFlagTimerO;  /*  d®c  timer  in  lower  6  bits  of  alphaFlag  V 
if  ((alphaFlag&$3f)  ==  0)  /*  if  time  to  change  prompt  state  V 

{ 

r  Toggle  the  state  of  the  prompt  V 

if  (PromptState      ON)  /*  bit  6  of  alphaFlag  =  1  V 

{  PromptOffO; 

} 

else 

{  PromptOnO; 
} 

} 

ReturnO; 

} 

DoMouse 


DoMouse: 
{ 

UpdateMouseO;  /  *  call  input  device  driver  for  new  positioning  V 

if  (mouseOn(MOUSEON_BIT)  ==  1)  r\\  mouse  is  on...  V 
{ 

FaultCheckO;  r  check  for  faults  V 

r  Commodore  machines  draw  the  mouse  here,  Apples  don't  V 
if(GEOS64||GEOS128)  /*  if  CBM  machine...  V 

{ 

DrawSprite(mousePicture)       r  copy  mouse  picture  into  sprite  data  tableV 

PosSprite{mouseXpox.mouseYpos)  /*  position  the  sprite  V 

if  (GEOS64)  /  *  if  GEOS  64...  V 

{     EnablSprite(MOUSE)  r  always  enable  the  sprite  each  time  "I 

} 

} 

ReturnO; 
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AppleSoftMouseService  

/*  Routine  to  move/draw  the  mouse  (sprite  #0)  during  interrupt  level  on  the  Apple. 
GEOS  128  soft-sprite  handler  does  a  similar  update  during  MainLoop.*/ 

AppleSoftMouseService: 
{ 

r  Only  draw  the  mouse  if  sprite  #0  is  enabled  and  mouse  is  not  temporarily  off  V 

if  (  (mobenble(BIT_0)  ==  1)  &&   (offFlag(BIT_7)  ==  0) 

{ 

/*  OK  to  update  the  mouse,  only  erase  if  not  yet  erased  V 
if  (  offFlag(BIT_6)  ==  0)  )  /*  if  mouse  not  yet  erased...  V 
{ 

/*  Has  the  mouse  moved  since  last  time?  Only  erase  if  no  movement  V 
if  (       (  lastYPos  I  =  (mouseYPos) )  || 

(  lastXPos  1=  (mouseXPos)  )  ) 

{ 

EraseSoftMouse(lastXPos,lastYPos);    /*  erase  if  mouse  moved  V 

} 

} 

offFlag  a  FALSE;         T  flag:  mouse  is  on  and  drawn  V 

/*  make  current  position  the  old  position  for  erasure  next  time  around  */ 
lastYPos  =  mouseYPos; 
(  ^  lastXPos  =  mouseXPos; 

DrawSoftMouse(mouseXPos,mouseYpos);         /*  draw  at  new  position  V 

) 

ReturnO; 

} 
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FaultCheck 


FaultCheck: 
{ 

/*  Check  mouse  against  left  constraint  and  left  screen  edge*/ 
if  {(mouseXPos  <  mouseLeft)  ||  (nnouseXPos  <  0)) 

{     mouseXPos  =  mouseLeft;  /*  force  mouse  to  constraint*/ 

faultData(OFFLEFT_BIT)  =  1;         /*  show  left  fault  */ 

} 

/*  Check  mouse  against  right  constraint  and  right  screen  edge*/ 
if  ((mouseXPos  >  mouseRight)  ||  (mouseXPos  >  SC_PIX_WIDTH-1)) 
{     mouseXPos  =  mouseRight;  /*  stop  mouse  at  edge  */ 

faultData(OFFRIGHT_BIT)  =  1 ;        /*  show  right  fault  */ 

} 

r  Check  mouse  against  top  constraint  and  top  screen  edge*/ 
if  ((mouseYPos  <  mouseTop)  ||  (mouseYPos  <  0)) 
{    mouseYPos  =  mouseTop;  /*  stop  mouse  at  edge  */ 

faultData(OFFTOP_BIT)  =  1;  /*  show  top  fault  */ 

} 

/*  Check  mouse  against  bottom  constraint  and  bottom  screen  edge*/ 
if  ((mouseYPos  >  mouseBottom)  ||  (mouseYPos  >  SC_PIX_HEIGHT-1)) 
(     mouseYPos  =  mouseBottom;  /*  stop  mouse  at  edge  */ 

faultData(OFFBOTTOM_BIT)  =  1;     /*  show  bottom  fault  */ 

} 

« 

if  (mouseOn(MENUON_BIT)  ==1)  /*  if  menus  on.  see  if  mouse  is  off  current  menu  */ 
{ 

i  f   (     (mouseYPos  <  menuTop)  || 

(mouseYPos  >  menuBottom)  || 

(mouseXPos  <  menuLeft)  || 

(mouseXPos  >  menuRight) 
)  /*  if  mouse  outside  any  menu  edge...  */ 

{     faultData(OFFMENU_BIT)  =  1;   /*  show  menu  fault  */ 
} 

} 

ReturnO; 
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MainLoop  Level  Pseudo-Code 

The  following  pseudo-code  diagrams  illustrate  the  general  MainLoop  Level  constructs  in  each  of 
the  three  systems  (GEOS  64,  GEOS  128,  Apple  GEOS).  This  pseudo-code  is  useful  for 
determining  exacdy  how  icons,  menus,  and  other  event-generating  mechanisms  interact  with  your 
application. 

MainLoop  


MainLoop: 
{ 


while  (TRUE) 
{ 

if  (APPLE) 

{     if  (offFlag(BIT7)  ==  1) 
{     offFlag  =  $40; 

} 

} 


r  This  loop  is  never  ending  */ 


/•  Apple  specific  */ 

/*  If  mouse  cursor  was  turned  off...  */ 

/*  Turn  it  back  on  now  that  weVe  in  MainLoop  V 


KeyboardServiceO; 

ProcessServiceO; 

SleepServiceO; 

if  (APPLE) 


{ 


r  service  keyboard  and  related  MainLoop  functions  V 
/*  service  processes  V 

/•  service  sleeping  routines  */ 

/*  Apple  differs  here,  too*/ 

r  let  aux  driver's  MainLoop  routine  do  what  it  needs  to  V 
r  Get  clock  driver  to  set  the  time  and  date  variables  V 


AuxDMainO; 
ReadClockO; 

AppleTimeServiceO;    /*  service  the  apple  time  V 

if  (intSource  ==  Software)  /*  if  generating  software  interrupts...  V 
{ 


} 

} 

else 
{ 


InterruptMainO; 


} 


CBMTimeServiceO; 


/*  simulate  interrupts  V 


/•  service  the  Commodore  time  V 


Calllndirect(applicationMain);   /  *  Call  any  application  code  that  NEEDS  to  be  handled 

Every  MainLoop  V 

}  /•  endwhile  V 
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KeyboardService  

KeyboardService: 
{ 

If  (C128  II  APPLE)        r  GEOS  128  and  Apple  GEOS  handle  sprites  here  V 
{  SoftSprHandlerO; 

} 

r  RUN  THROUGH  THE  BITS  IN  PRESSFU\G  AND  DISPATCH  AS  NECESSARY. 
THESE  DISPATCHES  GO  THROUGH  VECTORS  THAT  TYPICALLY  DEFAULT  TO 
GEOS  ROUTINES  FOR  HANDLING  THE  VARIOUS  USER-INPUTS  V 

/*  input  device  changed  vector  (currently  unused  by  GEOS)  V 
if  (pressFlag(INPUT_BIT)  ==1)      r  if  input  device  changed  V 
{ 

pressFlag(INPUT.BIT)  =  0)  /*  clear  flag  V 

Calllndirect(inputVector)         r  and  go  through  vector  «$0000»V 

} 

r  state  of  mouse  changed  vector  (mouse  moved;  state  of  button  changed) 

mouseVector  usually  points  to  an  internal  GEOS  routine  SystemMouseService()*/ 
if  (pressFlag(MOUSE_BIT)  ==1)     /*  if  mouse  state  changed...  */ 
{ 

pressFlag(MOUSE_BIT)  =  0)      /*  clear  flag  V 

Calllndirect(mouseVector)       /*  and  go  through  vector  «SystemMouseService»*/ 


/*  keyboard  character  ready 

keyVector  defaults  to  $0000.  V 
if  (pressFlag(KEYPRESS_BIT)      1)      /*  if  key  in  queue...  V 
{ 

keyData  =  GetCharFromQueue();     /*  get  keypress  */ 

if  (QUEUE_EMPTY)  /*  if  no  more  keys  in  the  queue...  V 

{ 

pressFlag(KEYPRESS_BIT)  =  0);     /*  clear  flag  V 

} 

Calllndirect(keyVector)  r  go  through  vector  «$0000»V 


r  any  mouse  faults  since  last  time? 

mouseFaultVec  usually  points  to  an  internal  GEOS  routine  SystemFaultServiceQV 
if  (faultData  1=  0)  /*  if  any  faults...  V 

{ 

Calllndirect(mouseFaultVec);  /*  go  through  vector  «SystemFaultService»V 
faultData  =  0;  /*  and  clear  faults  afterward  V 

} 

ReturnO; 
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ProcessService 


ProcessService: 
{ 

if  (numProcesses  >  0)        /  *  If  no  processes,  ignore  V 
{ 

for  (EachProcess)  /*  go  through  each  process  in  the  table. 

(start  with  last  in  table  &  work  backward)  V 

{ 

if  ((Process  ==  (RUNABLE  &  -BLOCKED))    /*  only  if  runable  &  not  blocked  V 
{     Process     -RUNNABLE;    r  clear  runable  flag  V 

ProcessEventO;  /•  and  generate  a  process  event  by  calling  the 

routine  in  the  table.  */ 

} 

} 

} 

ReturnO; 


SleepService 


SleepService: 
{ 

if  (numSleeping  >  0) 
{ 

for  (EachSleeping) 


if  (SleepTimer  =  0) 
{ 

RemoveSleepO; 
WakeUpO; 

} 

} 

} 

ReturnO; 

} 


/  *  If  no  slee;.  -^-^cs  V 

r  go  through  eacn     ..  .^i^s  in  the  table. 

(start  with  last  in  table  &  work  backward)  */ 

/*  if  counter  zero,  then  time  to  awake!  */ 

/*  remove  this  sleeper  from  the  internal  list  V 
r  and  go  wake  it  up*/ 
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MainLoop  and  Interrupt  Level:  a  Technical  Breakdown 


SytemMouseService 


SleepService: 
{ 

if  (  mouseData(BIT_7)  ==  DOWN  )    /*  if  mouse  button  down  (bit  ==  0)...  V 
{ 

if  (  mouseOn(MOUSEON_BIT)  ==1  )  T  if  mouse  checking  is  on...  V 
{ 

if  (  mouseOn(MENUON_BIT)  ==1)    /*  if  menus  scanning  is  on...  V 
{ 

/*  Check  if  the  mouse  is  within  the  currently  active  menu  (level  0/mairi)  V 
i  f   (     (mouseYPos  >  menuTop)  && 

(mouseYPos  <  menuBottom)  && 

(mouseXPos  >  menuLeft)  && 

(mouseXPos  <  menuRight)  ) 


MenuServiceO;  /*  mouse  was  pressed  on  menu,  go  handle  it  V 

ReturnO;  /*  Return  without  checking  icons  V 


} 

/*  Not  on  a  menu,  see  if  press  was  on  an  icon  V 

if  (  mouseOn(ICONSON_BIT)  ==1)   /*  if  icon  scanning  is  on...  V 

{ 

r  search  through  the  icon  table  looking  for  a  match  */ 

for  (Eachlcon) 

{ 

if  (icon(OFFJ_PIC)  !=  $0000)  /  *  if  icon  not  disabled...  V 
{ 

if  (MouseOnlconO     TRUE)      /*  if  mouse  on  top  of  this  icon...  V 
{ 

r  flash  or  invert  icon  as  necessary  V 
if  (iconSelFlag(ST_FLASH_BIT))     /*  flash  icon?  V 
{     InvertlconO;  /*  invert  once  V 

Sleep(selectionFlash);  /*  sleep  awhile  V 

InvertlconO;  /*  invert  back  again  V 

) 

else  if  (iconSleFlag(STJNVERT_BIT))         r  invert  icon?  V 
{     InvertlconO;  /*  just  invert  */ 

) 

/*  check  for  double  click  V 

if  (DBL^CLICK)       /*  if  this  is  the  second  click  of  a  dbl  click...*/ 
{     rOH  =  TRUE;  /*  set  double  click  flag  V 

} 

else  /  •  else,  set  single  click  flag  *. 

{     rOH  =  FALSE; 

} 

r  call  the  icon  event  routine*/ 

rOL  s  icon;  /*  tell  event  routine  which  icon  V 

Calllndirect(icon(OFFJ_EVENT));    /*  generate  an  event  */ 
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MainLoop  and  Interrupt  Level:  a  Technical  Breakdown 

Re  ..  n{);    /*  break  out  of  the  for  loop  (check  no  more  icons!)  V 

} 

} 

} 

} 

} 

} 

/*  If  we  got  here,  the  following  is  true: 

1 )  mouse  button  was  released  (as  opposed  to  pressed) 
-  or  - 

2 )  mouse  was  pressed,  but  not  on  an  icon  nor  on  a  menu 

V 

Calllndirect(otherPressVec);    T  it's  an  "other"  press.,  "other"  as  in  something  the 

system  doesn't  really  care  about  */ 
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MainLoop  and  Interrupt  Level:  a  Technical  Breakdown 


SytemFaultService  

SystemFaultService: 
{ 

f  only  deal  with  faults  if  the  mouse  is  on,  menu  scanning  is  enabled,  and  we've  got  a 

submenu  down...  */ 
if  (       (mouseOn(MOUSEON_BIT)  ==  1)  &&  (mouseOn(MENUON_BIT)  ==!)&& 

(menuNumber  >  0)  } 

{ 

if  (menuType  ==  CONSTRAINED) 
{ 

/*  for  constrained  menus...  */ 

/*  If  mouse  faulted  off  the  top  of  a  vertical  menu  or  off  the  left  of  a  horizontal 
menu,  then  we  go  to  the  previous  menu.  Otherwise,  the  fault  is  ignored  because 
the  menu  is  constrained  */ 

if  (       (menuType  ==  VERTICAL  &&  faultData(OFFTOP_BIT)  ==  TRUE)  || 

(menuType  ==  HORIZONTAL  &&  faultData(OFFLEFT_BIT)  ==  TRUE)  ) 

{ 

DoPreviousMenuQ; 

} 

} 

else     r  menuType  ==  UNCONSTRAINED  V 
{ 

DoPreviousMenuO;  /  *  always  try  to  go  to  the  previous  menu.  If  mouse  didn't 

move  onto  the  previous  menu,  then  next  pass  through 
mainloop  will  see  this  as  a  fiault  and  try  to  remove 
that  menu,  and  so  on  until  we're  back  to  the  main  menu 

*  / 

} 

ReturnO; 

} 
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Alphabetical  Listing  of 

Routines 


AllocateBlock 


lAllocateBlock  (Apple,  C64,  cm) 


mid-level  disk 


Function: 
Parameters: 


Uses: 


Returns: 


Alters: 


Destroys: 


Allocate  a  disk  block,  marking  it  as  in  use, 
CommcxiQrg: 

r6L       track  number  of  block  (byte). 
r6H      sector  number  of  block  (byte). 

Apple: 

r6        block  number  (word). 
curDrive 


Commodore: 
curDirHead 
dir2Headt 
dirSHeadt 

Apple: 

curVBlknot 

VBMchangedt 

numVBMBlkst 


this  buffer  must  contain  the  current  directory  header. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 


r6 

Apple: 
c 


error  ($00  =  no  error);  Commodore  only:  returns  BAD_BAM  if  block 

already  allocated. 

unchanged. 


carry  flag  is  set  if  block  is  already  in  use. 


Commodorg: 
curDirHead 
dir2Headt 
dirSHeadt 

Apple: 

curVBIknot 
VBMchanged^ 


BAM  updated  to  reflect  newly  allocated  block. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


used  by  VBM  cacheing  routines. 

set  to  TRUE  by  VBM  cacheing  routines  to  indicate  cached 
VBM  block  has  changed  and  needs  to  be  flushed 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
a,  y,  r7,  r8H. 


Description:  AllocateBlock  allocates  a  single  block  on  this  disk  by  setting  the  appropriate 
flag  in  the  allocation  map  (the  BAM  on  Commodore  computers  and  the  VBM  on 
Apple  computers). 


AllocateBlock 


Commodore:  If  the  sector  is  already  allocated  then  a  BAD_BAM  error  is  returned. 

AllocateBlock  does  not  automatically  write  out  tEe  BAM.  See  PutDirHead 
for  more  information  on  writing  out  the  BAM. 

The  Commodore  1541  device  drivers  do  not  have  a  jump  table  entry  for 
AllocateBlock.  All  other  device  drivers,  however,  do.  The  following 
subroutine  will  properly  allocate  a  block  on  any  device,  including  the  1 54 1 . 


NewAllocateBlock  —  allocate  specific  block  in  BAM 
with  any  CBM  GEOS  device  driver. 

Pass:        r6L,r6H  track, sector  to  allocate 

Uses:        BAM  in  curDirHead 

Returns:  x        error  status  ($00  =  success,  BAD_BAM 
block  already  in  use,  etc.) 

Destroys:  a,y, r7,r8H 

****************************************************** 

.if      (C64   I  I  C128) 
NewAllocateBlock : 


Idy  curDrive 

Ida  driveType-8,y 

and  #$0f 

cmp  #DRV_1571 

bcc  1541$ 

jmp  AllocateBlock 


1541$: 


jsr 
beq 

Ida 
eor 
and 

sta 
Idx 
dec 
Idx 
rts 


FindBAMBit 
110$ 

rSH 
#$ff 

curDirHead, x 

curDirHead, X 
r7H 

curDirHead, x 
#$00 


get  current  drive 

get  drive  type 

keep  only  drive  format 

see  if  1571  or  above 

branch  if  1541 

else,  use  driver  routine 


get  BAM  bit  info 
if  zero,  then  it's  not  free 
otherwise,  it's  free... 
get  bit  mask  for  BAM 
convert  to  clearing  mask 
and  with  BAM  byte  to  clear 

bit  and  show  as  allocated 
and  store  back, 
get  base  of  track's  entry 
dec  #  free  blocks  this  track 
show  no  error 
exit 


Apple: 


110$: 

Idx 
rts 
.endif 


*BAD  BAM 


show  error 
exit 


already  in  use 


Apple  GEOS  did  not  include  AllocateBlock  in  its  jump  table  until  version  2.1. 
The  following  patch  places  the  entry  into  the  jump  table,  thereby  allowing 
applications  to  call  AllocateBlock  under  version  2.0  (which  was  the  first 
version  of  Apple  GEOS). 


.if  (APPLE) 

LowSwitch  =  $fcl6 

o_AllocateBlock  «  $45cl 

JMPABS  =  $4c 

VER_2  0  =  $20 


;  direct  entries  into  Kernal;  do  not  use 

;  except  for  authorized  patches 

;  JMP  absolute  opcode 

;  version  2.0 


PatchAllocateBlock : 
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AllocateBlock 


Ida 

version  ; 

get  Kernal  version  number 

cmp 

#VER_2_0  ; 

check  against  version  2.0 

bne 

99$  ; 

if  not  v2.0,  then  no  patch  necessary 

Ida 

#JMPABS  , 

store  jmp  LowSwitch  into  main 

sta 

AllocateBlock  , 

jump  table 

Ida 

#(LowSwitch  , 

sta 

AllocateBlock+1  , 

Ida 

#]LowSwitch  , 

sta 

AllocateBlock +2 

sta 

RAMWRT_ON 

;  switch  in  aux  bank 

Ida 

#JMPABS 

?  store  jmp  o__AllocateBlock  into  aux 

sta 

AllocateBlock 

;  jump  table 

Ida 

# [o_AllocateBlock 

sta 

AllocateBlock+1 

Ida 

# ] o_AllocateBlock 

sta 

AllocateBlock+2 

sta 

RAMWRT_OFF 

;  switch  back  to  main  bank 

99$:  rts 

;  exit 

.endif  ; (APPLE) 

Example: 


MoveW 

DiskBlock,  r6 

i 

block  to  allocate 

.if  (C64   1 1 

C128) 

jsr 

NewAllocateBlock 

(see  above) 

cpx 

#BAD_BAM 

BAD_BAM  means  block  in  use 

beq 

200$ 

branch  if  block  already  in  use 

txa 

check  for  other  error 

beq 

150$ 

branch  if  no  error 

jmp 

MyDiskError 

call  error  handler  with  error  in 

.else  / (APPLE) 

jsr 

AllocateBlock 

Allocate  the  block 

php 

! 

save  status  of  allocation 

txa 

r 

get  error  status 

beq 

100$ 

f 

branch  if  no  error 

pip 

! 

error:  fix  stack 

jmp 

MyDiskError 

f 

call  error  handler  with  error  in 

100$: 

pip 

restore  status  of  allocation 

bcs 

200$ 

! 

branch  if  block  already  in  use 

.endif 


150$:                                                ;  block  was  free  and  is  now  allocated 
;         code  to  handle  new  block  goes  here   

200$:  ;  block  is  not  free... 

/         code  to  handle  block  already . allocted  goes  here   

MyDiskError:                                      /  error  occurred... 
;         code  to  handle  disk  errors  goes  here   

.ramsect 

DiskBlock  .block  2  ;  disk  block  to  allocate 

.psect 


See  also:        SetNextFree,  BlkAlIoc,  FreeBlock. 
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AppendRecord 


AppendRecord  (Apple,  C64,  cns) 


VLIR  disk 


Function:       Adds  an  empty  record  after  the  current  record  in  the  index  table,  moving  all 
subsequent  records  down  one  slot  to  make  roonx 


Parameters:  none. 
Uses: 


Returns: 
Alters: 


Destroys: 
Description: 


curDrive 
nieWrittent 

curRecord 
fileHeader 

Commodore: 

curType 

curDirHead 

dirlHeadt 

dirSHeadt 

Apple: 

curVBlknot 

VBMchangedt 

numVBMBlkst 


if  FALSE,  assumes  record  just  opened  (or  updated)  and 

reads  B  AWVBM  into  memory. 

current  record  pointer 

VLIR  index  table  stored  in  this  buffer. 


GEOS  64  v1 ,3  and  later:  for  detecting  REU  shadowing, 
current  dirtciovy  header/BAM. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
X  error  ($00  =  no  error). 


curRecord 

usedRecords 

fileWrittent 

fileHeader 

Commodore: 
curDirHead 


new  record  becomes  the  current  record, 
incremented  by  one. 

set  to  TRUE  to  indicate  die  file  has  been  altered  since  last 
updated. 

new  record  added  to  index  table. 


directory  header  read  in  if  file  Written  is  FALSE  on  call. 
^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
a,  y,  rOL,  rlL,  r4. 

AppendRecord  inserts  an  empty  VLIR  record  following  the  current  record  in 
the  index  table  of  an  open  VLIR  file,  moving  all  subsequent  records  down  in  the 
record  list.  The  new  record  becomes  the  current  record.  A  VLIR  file  can  have  a 
up  to  MAX_VLIR  RECS  records  (127  on  the  Commodore  and  254  on  the 
Apple).  If  adding  a  record  exceeds  this  value,  then  an  OUT^OF^RECORDS 
error  is  returned. 

A  record  added  with  AppendRecord  occupies  no  disk  space  until  data  is  written 
to  it.  The  new  record  is  marked  as  empty  in  the  VLIR  index  table.  (When  a  VLIR 
file  is  first  created  by  SaveFile,  all  records  are  marked  as  unused).  Some 
applications  call  AppendRecord  repeatedly  after  creating  a  new  file  until  an 
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AppendRecord 


Note: 


Apple: 


CBM: 


OUT_OF_RECORDS  error  is  retumed  This  marks  all  the  records  as  used  and 
prepares  tfiem  to  accept  data  with  calls  to  WriteRecord. 

AppendRecord  does  not  write  the  VLIR  index  table  out  to  the  disk.  Call 
CioseRecordFile  or  UpdateRecordFiIe  to  save  the  index  table  when  all 
modifications  are  complete. 

An  empty  record  is  marked  with  $ffff  in  the  VLIR  index  table  (stored  in  the  buffer 
at  fileHeader).  An  unused  record  is  marked  with  $0000.  Use  PointRecord  to 
check  the  status  of  a  particular  record  (unused,  empty,  or  filled). 

An  empty  record  is  marked  with  $ffOO  in  the  VLIR  index  table  (stored  in  the 
buffer  at  fileHeader).  An  unused  record  is  marked  with  $0000.  Use 
PointRecord  to  check  the  status  of  a  particular  record  (unused,  empty,  or 
fiUed). 


Example: 


SaveRecord: 
LoadW 
jsr 
txa 
bne 
Ida 
jsr 
txa 
bne 
jsr 
LoadW 
LoadW 
jsr 
txa 
bne 
jsr 


rO,  IFilename 
OpenRecordFile 

99$ 

appendPoint 
PointRecord 

99$ 

AppendRecord 
r7,  #BufStart 
r2,  #BUFLENGTH 
WriteRecord 

99$ 

CioseRecordFile 


99$: 


rts 


pointer  to  filename 
open  VLIR  file 
check  open  status 
exit  on  error 
get  record  to  append  to 
go  to  that  record 
check  point  status 
exit  on  error 

ajppend  a  record  at  this  point 
point  at  data  buffer 
bytes  in  buffer  (bufEnd-buf Start) 
write  buffer  to  record 
get  write  status 
exit  on  error 
close  VLIR  file 

;  return  with  any  error  in  x 


.ramsect 

appendPoint : 

Filename: 

BufStart 

BUFLENGTH 

.psect 


.block  1 

.block  NAME_LENGTH+1 

.block  1024 

o  (*  -  bufStart)+l 


record  to  append  to 

holds  null-terminated  filename 

data  buffer 

length  of  buffer 


See  also: 


InsertRecord,  DeleteRecord,  PointRecord. 
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AuxDExit 


AuxDExit  (Apple) 


aux  driver! 


Function: 


De-install  and  remove  the  current  aux  driver. 


Parameters:  none. 

Returns:        a         bit  7  set  if  reinitialization  required. 
Destroys:       assume  x,  y,  r0-rl5. 

Description:  The  GEOS  deskTop  calls  AuxDExit  prior  to  loading  a  new  aux  driver.  This 
allows  the  current  aux  driver  to  deinstall  itself  properly,  removing  any  hooks  it 
may  have  placed  into  the  operating  system.  A  RAMdisk  aux  driver,  for  example, 
would  need  to  remove  itself  from  the  device  table  before  it  can  be  replaced.  The 
GEOS  deskTop  and  the  Configure  utility,  for  example,  will  call  AuxDExit  prior 
to  replacing  the  current  auxiliary  driver. 

If  bit  7  of  a  is  set  on  return,  then  this  indicates  that  the  device  table  has  changed 
and  a  reset  is  in  order.  The  deskTop,  for  example,  will  reinitialize  itself  if  bit  7  is 
set.  This  is  equivalent  to  choosing  RESET  from  the  options  menu. 


Example: 


SAMPLE  AuxDExit  ROUTINE  *** 

o  AuxDExit  —  Deinstall  RamFactor  Auxiliary  driver 


Synopsis : 


Called  by: 
Pass : 

Returns:  X 
A 


Before  loading  another  aux  driver,  control  vectors 
through  the  AuxDExit  entry  in  the  aux  driver's  jump 
table.  This  is  the  AuxDExit  routine  for  the  Ram  Factor 
RAM  disk  driver.  We  leave  the  drive  in  the  drive  list 
but  restore  the  original  ProDOS  vector. 

Aux  driver  jump  table  AuxDExit  entry. 

Nothing 

error  status  (NOT_IMPLEMENTED  is  returned  if  unable  to 
uninstall 

=  0  for  no  RESET  needed 
=  $80  if  reset  needed 


AUXRESET 

AUXNORESET 

RamExit : 
Ida 
sta 
Idx 
jsr 
beq 
Idy 
Idx 


10$: 


jsr 


$80 


=  $00 


#$ff 

DD_Command 
curDrive 
IsPatched 
110$ 

#AUXNORESET 
numD  rive's 


IsPatched 


flag  to  force  RESET  function  if  we  change 

the  drive  tables 

and  for  not  resetting... 


Get  current  drive 

Check  current  drive  against  this  driver 
Can't  uninstall  current  drive,  do  error 
assume  no  reset  necessary 
We're  OK.  go  through  each  drive  in  the 
drive  table  and  if  it's  a  RAM  factor, 
then  restore  the  old  vector 

see  if  this  drive  is  patched 
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AuxDExit 


bne 
Idy 
Ida 
sta 
Ida 
sta 

dex 
bpl 

tya 
Idx 
rts 

Idx 
Ida 
rts 


IsPatched: 

Ida 
cmp 
bne 
Ida 
cmp 
rts 


20$: 


100$: 


110$: 


20$ 

#AUXRESET 
auxDevTabLo,  x 
devTabLo, x 
auxDevTabHi,  X 
devTabHi,x 


10$ 


#N0  ERROR 


#NOT_IMPLEMENTED 
#AUXNORESET 


devTabHi,x 

# ] PatchRamFactor 

20$ 

devTabLo, x 

# [PatchRamFactor 


if  not,  then  skip  it 

found  a  patched  entry,  enable  RESET 

and  put  back  the  real  entry  point 


try  next  drive 

and  loop  until  no  more 

put  RESET  flag  in  accumulator 

and  return  no  error 

exit 

return  error 

no  need  to  RESET 


Pass:  device  number  in  X 
Returns:  result  of  compare  in  ST 
Check  address  of  this  aux  patch 
against  vector  in  device  table  for 
equality. 


exit 
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AuxDInt 


AuxDInt  (Apple) 


aux 


driver 


Function: 


Aux  driver  Interrupt  Level  routine. 


Parameters: 


none. 


Returns: 


nothing. 


Destroys:       assume  a,  x,  y,  r0-rl5. 

Description:    Apple  GEOS  calls  AuxDInt  during  Interrupt  Level.  This  allows  an  aux  driver  to 


have  routines  that  execute  at  Interrupt  Level.  With  a  hardware  interrupt  source, 
Interrupt  Level  will  execute  approximately  every  vertical  blank  (60  times  per 
second). 

An  aux  driver  that  has  no  need  for  Interrupt  Level  processing  should  simply 
perform  an  rts. 


See  also: 


AuxDMain. 


8 


AuxDKeyFilter 


AuxDKeyFilter  (Apple) 


aux  driver 


Function: 

Parameters: 
Returns: 


Description: 


Note: 


Aux-driver  keypress  filter;  pre-processes  keyboard  input  so  aux  driver  may 
interpret  special  keystrokes. 


a 
a 


KEY  —  key  as  scanned  from  keyboard  circuitry, 
translated  character  or  NULL  if  filtering  out 


Destroys:       x,  y 


An  application  does  not  call  AuxDKeyFilter  directly.  The  Apple  GEOS 
keyboard  scanning  routine  calls  AuxDKeyFilter  at  Interrupt  Level  immediately 
after  calling  KeyFilter.  This  allows  the  aux  driver  to  translate,  remap,  or  filter- 
out  certain  keypresses. 

A  typical  AuxDKeyFilter  routine  compares  the  KEY  parameter  against  a  list  of 
specific  keypresses.  If  there  is  no  match,  then  AuxDKeyFilter  returns  without 
altering  the  KEY  code.  If  there  is  a  match,  AuxDKeyFilter  can  perform  some 
action  in  response  and  return  a  different  KEY  value  or  a  KEY  value  of  NULL. 
(A  KEY  value  of  NULL  effectively  filters  out  the  keypress  because  GEOS 
ignores  the  "null-key"  value,  never  placing  the  key  in  the  keyboard  input  queue.) 

UKEY  is  NULL  when  AuxDKeyFilter  is  called,  then  a  key  was  pressed  but  it 
has  already  been  processed  by  some  other  prior  filter  (most  likeley  KeyFilter) 
and  should  be  ignored. 

The  KEY  parameter  comes  from  the  Apple  hardware  register  KEYBD_DAT A. 
GEOS  then  sets  high-bit  is  set  to  reflect  the  state  of  the  Option  or  ll  key 
(keyboards  that  have  one,  don't  have  the  other).  If  bit  7  is  set,  then  that  key  is 
pressed  To  detect  the  state  of  the  C5  key,  check  the  OPEN_APPLE  hardware 
location.  ~ 


Example: 


;Check  for  open-apple  key 
bit  OPEN_APPLE 
bmi  OpenPressed 


; check  open  apple  key  status 
/branch  if  pressed 


***  SAMPLE  AuxDKeyFilter  ROUTINE  *** 

o_AuxDKeyFilter  —  key  filter  routine  for  screen  dump  aux  driver 

Synopsis:  At  each  keypress,  GEOS  vectors  through  the  aux  driver's 

AuxDKeyFilter  jump  table  entry  which  points  here. 

Called  by:        AuxDKeyFilter  entry  in  Aux  driver's  jump  table. 

Pass:  key  in  A 

Returns:  key  value  unchanged  or  NULL  if  it's  the  key  we're  looking 

for 

MAGIC^KEY  =  ($80  I    '!')  /close-apple  +  shift  +  1 


o_AuxDKeyFilter : 


9 


AuxDKeyFllter 


99$: 


cmp 
bne 
jsr 
Ida 

rts 


#MAGIC_KEy 
99$ 

DoDump 
#NULL 


check  keypress  against  our 
if  no  match,  then  ignore 
else,  do  screen  dump 
and  return  a  null  key 

exit 


DoDump: 

;         code  to  handle  screen  dump  goes  here 


See  also: 


KeyFilter. 
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AuxDMain 


AuxDMain  (Apple) 


aux  driver! 


Function :       Aux  driver  MainLoop  Level  processing. 

Parameters:  none. 

Returns:  nothing. 

Destroys:       assume  a,  x,  y,  r0-rl5. 

Description:    Apple  GEOS  calls  AuxDMain  on  every  pass  through  MainLoop.  This  allows 
an  aux  driver  to  have  MainLoop  Level  functions. 

An  aux  driver  that  has  no  need  for  MainLoop  Level  processing  should  simply 
rts. 


See  also: 


AuxDInt. 


11 


BBMult 


BBMult  (Apple,  C64,  C128) 


math 


Function: 
Parameters: 


Returns: 


Unsigned  byte-by-byte  multiply:  multiplies  two  unsigned  byte  operands  to 
produce  an  unsigned  word  result 

X  OPERANDI  —  zero-page  address  of  single-byte  multiplicand  in  the 
low-byte  of  a  word  variable  (byte  pointer  to  a  word  variable). 

y  0PERAND2  —  zero-page  address  of  the  byte  multiplier  (byte  pointer  to 
a  byte  variable). 

Note:  result^  OPERANDI  (byte)  *  0PERAND2(byte). 

X,  y,  and  byte  pointed  to  by  OPERANDI  unchanged, 
word  pointed  to  by  OPERANDI  contains  the  word  result. 


Destroys:       a,  r7L,  r8 


Description: 


Note: 


BBMult  is  an  unsigned  byte-by-byte  multiplication  routine  that  multiplies  two 
bytes  to  produce  a  16-bit  word  result  (low/high  order).  The  byte  in  OPERANDI 
is  multiplied  by  the  byte  in  OPERANDI  and  the  result  is  stored  as  a  word  back  in 
OPERANDI.  Note  ihoxOPERANDl  starts  out  as  a  byte  parameter  but  becomes  a 
word  result  with  the  high-byte  at  OPERAND 

Because  r7  and  r8  are  destroyed  in  the  multiplication  process,  they  cannot  be 
used  to  hold  either  operand. 

No  overflow  can  occur  when  multiplying  two  bytes  becuase  the  result  always  fits 
inaword($ff*$ff  =  $fe01). 


Example: 


Multiply  rlL  by  rlH  and  store  the  word  result  in  r2 

MoveB  rlL, r2L  ;  r2L  <-  rlL  copy  of  OPERANDI 

•   Idx  #r2L  /  point  to  copy  of  OPERANDI  (r2L) 

Idx  #rlH  ;  point  to  0PERAND2  (rlH) 

jsr  BBMult  ;  r2  <-  r2L  *  r2H    do  multiplication 


SeeAlso: 


BMult,  DMult,  Ddiv,  DSdiv. 
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Bell  (Apple) 


utili 


Function: 

Parameters: 

Returns: 

Destroys: 

Description: 

Note: 


Makes  a  brief  beeping  sound  through  the  Apple's  internal  speaker, 
none, 
nothing. 

x,y 

Bell  sounds  a  1000  Hz  signal  through  the  Apple's  internal  speaker.  The  sound 
lasts  approximately  1/1 0th  of  a  second. 

Bell  does  not  return  until  after  the  full  duration  of  the  sound.  Interrupts  are 
disabled  during  this  period.  The  interrupt-disable  status  is  restored  when  Bell 
returns. 

C64  &  C128:  The  following  routine  provides  a  bell  sound  under  Commodore  GEOS.  It  is 
provided  for  portability. 

.if  (064   I  I  C128)  ;  only  for  Commodore  versions;  use  Kernal 

;  routine  on  Applf. 

Bell  —  Make  a  bell  sound  on  C64/128 

Author:  Dan  Kaufman  (w  Chris  Hawley) 

(mgl) 

Pass:  Nothing 
Return:  Nothing 
Destroyed:  a 

Synopsis:        This  routine  allows  you  to  have  the  c64  beep  when  the  user 
makes  a  mistake  or  does  something  he  shouldn't. 


sidBase 
voicelRegs 


«  $D400 
sidBase 


f reqLol 

as 

voicelRegs 

freqHil 

voicelRegs+1 

PWLol 

rs 

voicelRegs+2 

PWHil 

voicelRegs+3 

controlRegl 

voicelRegs+4 

att_decl 

voicelRegs+5 

sus__rell 

ss 

voicelRegs+6 

FCLo 

voicelRegs+7+7+$7 

FCHi 

voicelRegs +7 +7 +$8 

res_filt 

voicelRegs+7+7+$9 

mode_vol 

voicelRegs+7+7+$A 

pulse 

%01000001 

SOUND  ON 

$30 

Bell: 


PushB  CPU_DATA 

LoadB        CPU_DATA,#IO  IN 


/switch  to  I/O  space 
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Bell 


LoadB 

controlRegl, #0 

sta 

att__decl 

LoadB 

mode__vol,  #$18 

LoadB 

sus_rell, #SOUND_ON 

LoadW 

PWLol,#$800 

LoadB 

FCLo,#0 

sta 

FCHi 

sta 

res__f  ilt 

LoadB 

att_decl,#6 

LoadB 

sus__rell,  #0 

LoadB 

freqLol,#$DF 

LoadB 

freqHil,#$25 

LoadB 

controlRegl, #puise 

PopB 

CPU__DATA 

rts 

/twiddle  sound  chip 


; return  to  memory  space 


.endif  ; (C64   I  1  C128) 


Example: 


r***  Beep  three  times  *** 

r         Runs  off  of  MainLoop  by  using  Sleep 


BELL_INTERVAL 

=  (FRAME_ 

_RATE/10) 

approx 

1/10  second 

BeepThrice : 

jsr 

Bell 

•  sound 

the  bell 

LoadW 

rO,  #BELL_ 

_INTERVAL 

'  pause 

a  bit 

jsr 

Sleep 

jsr 

Bell 

•  sound 

the  bell  again 

LoadW 

rO,#BELL_ 

_INTERVAL 

•  pause 

a  bit 

jsr 

Sleep 

jmp 

Bell 

•  sound 

the  bell  again 
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BitmapClip 


BitmapClip  (Apple,  C64,  cns) 


graphics 


Function:       Place  a  rectangular  subset  of  a  compacted  bitmap  on  the  screen. 


Parameters: 


Uses: 

Returns: 

Destroys: 

Description: 


rO        DATA  —  pointer  to  the  compacted  bitmap  data  (word). 
rlL      XPOS  —  X  card  position:  pixeLposition  /8  (byte). 
rlH      Y  —  y-coordinate  (byte). 

r2L      W^WIDTH  —  clipping  window  width  in  cards:  pixeLwidth/8  (byte). 

r2H      W^HEIGHT  —  height  in  pixels  of  clipping  window  (byte). 

rllL     DXl  —  delta-xl:  offset  of  left  edge  of  clipping  window  in  cards  from 

left  edge  of  full  bitmap  (byte), 
r  IIH    DX2  —  delta-x2:  offset  of  right  edge  of  clipping  window  in  cards  from 

right  edge  of  full  bitmap  (byte). 
rl2       DYl  —  delta-yl:  offset  of  top  edge  of  clipping  window  in  pixels  from 

top  edge  of  full  bitmap  (word). 

where  the  upper-left  corner  of  the  clipped  bitmap  (the  window)  is  placed  at 
(XP0S*8,  Y).  The  lower-right  corner  is  at  ([XPOS*8]+[WJVIDTH*8], 
Y-^W^H  EIGHT). 

dispBufferOn: 

bit  7  —  write  to  foreground  screen  if  set. 
bit  6  —  write  to  background  screen  if  set 

nothing. 

a,  X,  y,  r0-rl2 

BitmapClip  uncompacts  a  rectangular  area  of  a  full  bitmap,  clipping  (ignoring) 
any  data  that  exists  ouside  of  the  desired  area.  The  rectangular  subset  is  called  the 
clipping  window. 
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BitmapClip 


The  following  diagram  illustrates  the  eight  BitmapClip  parameters: 

full  compacted  bitmap 


DYf 
(in  pixels) 

W_HEIGH1 
(in  pixels) 


Note: 


C128: 


Apple: 


clipping  window, 


eight-pixel 
boundaries 


DX1 
(in  cards) 


WJA/IDTH 
(in  cards) 


DX2 
(in  cards) 


No  checks  are  made  to  determine  if  the  data,  dimensions,  or  positions  are  valid. 
Be  careful  to  pass  accurate  values.  Do  not  pass  a  value  of  $00  for  either  the 
WJWIDTH  or  WJiEIGHT  parameters,  and  pay  special  attention  to  the  fact  that 
XPOS,  WJWIDTH,  DXl,  and  DX2  are  specified  in  cards  (groups  of  eight  pixels 
horizontally),  not  in  individual  pixels. 

It  may  be  helpful  to  think  of  DYl  as  the  number  of  scanlines  in  the  bitmap  to  skip 
initiallly,  to  think  of  W_H EIGHT  as  the  number  of  scanlines  to  display,  to  think 
of  DXl  as  the  number  of  cards  to  skip  at  the  beginning  of  each  scanline,  to  think 
of  W_WIDTH  as  the  number  of  cards  to  display,  and  to  think  of  DX2  as  the 
number  of  bytes  to  skip  at  the  end  of  each  scanline. 

Under  GEOS  128,  OR'ing  DOUBLE^B  into  the  XPOS  and  W^WIDTH 
parameters  automatically  doubles  the  x-position  and  the  width  of  the  bitmap 
(respecitvely)  when  running  in  80-column  mode. 

BitmapClip  in  the  first  release  of  GEOS  128  does  not  call  TempHideMouse 
to  disable  the  sprites  and  does  not  properly  double  the  width  when  drawing  to  the 
80-column  screen.  On  Kemals  where  the  release  byte  is  greater  than  $01,  these 
problems  have  been  fixed 

DOUBLE__B  may  be  OR'ed  into  the  WJVIDTH  parameter  to  double  the  bitmap 
width  and  INAUX_B  may  be  OR'ed  into  the  XPOS  parameter  to  specify 
auxiliary  memory.  " 
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BitmapClip 


Example: 


************************************** 


Displaylmage 


Pass : 


Destroys : 


General  purpose  routine  to  display  a  portion  of 
compacted  bitmap  image  in  a  window 

pixBuf  compacted  bitmap  image  in  pseudo-photoscrap 

format.  Byte  0  is  card  width  of  image. 
Byte  1  and  2  is  the  pixel  height  (word) . 
The  compacted  image  data  starts  at  byte  3. 
xOffset  card  index  into  bitmap  to  display 

yOffset  pixel  index  into  bitmap  to  display 

a,x,  y,  r0-rl2 


WINDOW__X  =  4 

WINDOW_Y  =  30 

WINDOW_WIDTH  »  5 

WINDOW__HEIGHT  «  60 

Displaylmage: 

Set  up  initial  parameters  **" 

LoadW  rO,#PixImage 

LoadB  rlL,  #WINDOW__X 

LoadB  rlH,  #WINDOW__Y 

LoadB  r2L, #WINDOW_WIDTH 

LoadB  r2H, #WINDOW_HEIGHT 

MoveB  xOffset^rllL 

MoveW  yOffset,rl2 

;***  Clip  to  window  *** 
Ida  PixWidth 
sec 

sbc  WINDOW__WIDTH 

—  following  line  changed  to 

—  use  zero-page  copy 


10$: 


card  x-position  of  window 
pixel  y-position  of  window 
card  width  of  window 
pixel  height  of  window 


rO  <-  compacted  picture  data  (DATA) 
rlL  <-  left  edge  of  window  (XPOS) 
rlH  <-  top  edge  of  window  (Y) 
r2L  <-  width  of  window  (W_WIDTH) 
r2H  <-  height  of  window  (W__HEIGHT) 
rllL  <-  X  offset  into  bitmap  (DX.l) 
rl2  <-  y  offset  into  bitmap  (DYl) 


get  bitmap  width 
subtract  window  width 


sbc 

xOffset  , 

?  subtract  x-index  into  bitmap 

sbc 

rllL 

?  now  we  have  the  right  edge  clip  distance 

sta 

rllH 

?  rllH  <-  right  edge  clip  (DX2) 

bpl 

10$ 

?  if  we're  >0,  branch  to  skip  x  clipping 

adc 

#WINDOW_WIDTH 

?  add  back  the  window  width 

sta 

r2L 

;  ma)ce  that  the  new  clip  window 

LoadB 

rllH,#0 

?  rllH  <-  $00  (fixes  underflow  of  DX2) 

Ida 

PixHeight 

?  subtract  window  height  from  bitmap  height 

sec 

?   (two  byte  subtractiqn) 

sbc 

#WINDOW_HEIGHT 

sta 

r3L 

;  store  intermediateresult  in  r3 

Ida 

PixHeight+1 

sbc 

#0 

sta 

r3H 

Ida 

r3L 

;  now  subtract  y  index  into  bitmap 

sec 

following  line  changed  to 

use  zero- 

page  copy 

sbc 

yOf f set 

sbc 

rl2L 

;   (rl2  =  yOffset) 

sta 

r3L 

Ida 

r3H 

following 

line  changed  to 

use  zero- 

page  copy 

sbc 

yOf f set+1 
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BitmapClip 


20$: 
99$: 


ramsect 
f  fset 
•  set 

-  ..    ^  -dth 
Pixhaight 
Piximage 
.psect 


sbc 

rl2H 

sta 

r3H 

bpl 

20$ 

Ida 

r3L 

adc 

#WINDOW__HEIGHT 

sta 

r2H 

jsr 

BitmapClip 

rts 

.block  1 
.block  2 
.block  $800 
PixBuf+0 
PixBuf+1 
PixBuf+3 


(rl2  =  yOffset) 

value  in  r3H  never  used  after  this 
branch  if  no  underflow 

correct  for  underflow 


display  the  bitmap  with  clipping 
exit 


.:d  X  index  into  bitmap  (byte) 
i^xel  y  index  into  bitmap  (word) 
2K  picture  buffer 
width  of  picture  in  cards  (byte) 
height  of  picture  in  pixels  (word) 
start  of  bitmap  image 
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BitmapUp 


BitmapUp^  i  BitmapUp  (Apple,  C64,  ci28) 


graphics 


Function: 
Parameters: 


Place  a  compacted  bitmap  onto  the  screen. 


Uses: 

Returns: 
Destroys: 


Description: 


128: 


Normal: 
rO  DATA 
rlL 


pointer  to  the  compacted  bitmap  data  (word). 
XPOS  —  X  card  coordinate:  pixeLposition  /8  (byte). 
Y  —  y-coordinate  (byte). 
WIDTH  —  width  in  cards:  pixeLwidth/8  (byte). 
HEIGHT  —  height  in  pixels  (byte). 


rlH 
r2L 
r2H 

Inline: 

data  appears  immediately  after  the  jsr  i_BitmapUp 
.word  DATA        pointer  to  the  compacted  bitmap  data, 
.byte   XPOS        x  card  position:  pixeLposition  /8. 
.byte   Y  y-coordinate. 
.byte   WIDTH      width  in  cards:  pixeLwidth/8. 
.byte   HEIGHT     height  in  pixels. 

where  the  upper-left  corner  of  the  bitmap  is  placed  at  (XP0S*8,Y).  The  lower- 
right  corner  is  at  (XPOS*8+WIDTH^8,Y+HEIGHT). 

dispBufferOn: 

bit?  — write  to  foreground  screen  if  set. 
bit  6  —  write  to  background  screen  if  set 

nothing. 

Commodore: 
a,  X,  y,  rO-r9L 

Apple; 

a,  X,  y,  r0-r2 

BitmapUp  uncompacts  a  GEOS  compacted  bitmap  according  to  the  width  and 
height  information  and  places  it  at  the  specified  screen  position.  No  checks  are 
made  to  detemiine  if  the  data,  dimensions,  or  positions  are  valid,  and  bitmaps 
which  exceed  the  screen  edge  will  not  be  clipped.  Be  careful  to  pass  accurate 
values.  Do  not  pass  a  $00  for  the  WIDTH  or  the  HEIGHT  parameter,  and  pay 
special  attention  to  the  fact  that  both  the  x-position  and  the  width  are  specified  in 
cards  (groups  of  eight  pixels  horizontally),  not  in  pixels. 

Under  GEOS  128,  OR'ing  DOUBLE^B  into  the  XPOS  and  WIDTH  parameters 
will  automatically  double  the  x-position  and  the  width  (respectively)  in  80-column 
mode.  The  first  release  of  GEOS  128  did  not  properly  remove  the  sprites  before 
placing  the  bitmap  on  the  screen.  The  easiest  way  to  correct  for  this  is  to  always 
precede  a  call  to  BitmapUp  with  a  call  td  TempHideMouse.  The  redundant 
call  to  TempHideMouse  when  running  under  later  releases  is  minimal 
compared  to  the  number  of  cycles  it  takes  to  decompact  and  draw  the  bitmap. 


jsr        TempHideMouse  ; correct  for  bug  in  release  1  of  GEOS  128 

jsr        BitmapUp  ;then  put  up  the  bitmap 
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BitmapUp 
Apple: 


Example: 


See  also: 


Under  Apple  GEOS,  DOUBLE^B  may  be  OR'ed  into  the  WIDTH  paramter  to 

double  the  bitmap  width  and  INAUX_B  may  be  OR'ed  into  the  XI  parameter  to  f 

specify  auxiliary  memory.  "" 


;Put  a  bitmap  up  from  an  address  in 
/auxiliary  memory  and  doubling  the 


/picture ' s 

width. 

.if  (APPLE) 

LoadW 

rO, #MyAuxBitmap 

/  rO  <-  aux  address  of  bitmap 

LoadW 

rlL, #(MY_CXPOS|INAUX  B) 

/  r3  <-  card  x-pos  +  in-aux 

LoadB 

rlH,#MY_YPOS 

/  rlH  <-y-coordinate 

LoadB 

r2L, # (MY_CWIDTH 1  DOUBLE  1 W) 

/  r2L  <-  card  width  +  double  bit 

LoadB 

r2H,#MY_HEIGHT 

/  r2H  <-  height 

jsr 

BitmapUp 

/  put  bitmap  on  screen 

.endif 


•k'kitlt'k-k'kic'klfk-tfk'k'k'k'ti-k 

***  ShowBitmap  *** 
****************** 

For  C64,  C128,  or  Apple 
if      (C128  &&  C64) 

.echo  ShowBitmap  cannot  assemble  for  both  C64  and  C128  at  the  same  time 
endif 


BM_XPOS 
BM_YPOS 

Bitmap; 


(32/8) 
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/card  x-pos it ion  of  bitmap 
/y-position  of  bitmap 


BMJWIDTH 
BM  HEOIT 


-  PicW 

-  PicH 


ShowBitmap: 


Ida 

#(STjm_FORE  1  ST_WRjaACK)  , 

>  use  both  screens 

sta 

dispBufferOn  i 

.if  (C128) 

'  bug  fix  for  128  release  1 

jsr 

TenpHideMouse  < 

remove  sprites 

•endif 

jsr 

i^BitmpUp  , 

*  inline  bitmap  call 

•word 

Bitmap  ^ 

♦bitmap  address 

.byte 

(BM  XPOSI  (DOUBIf:  B&(!APPLE*- 

-1)));   *xpos  (can't  dbl  on  apple) 

.byte 

BMJfPOS 

*ypos 

.byte 

(BM  WIDTH  (DOUBLE  B) 

★width 

.byte 

BM  HEIGHT 

♦height 

card  width  of  bitmap 
bitmp  height 


Place  the  bitmap  on  the  screen, 
loading  the  registers  with 
inline  data  (note  double-width 
settings) . 


90$:  rts 

BitmapCIip,  BitOtherClip,  NewBitUp. 


exit 


20 


BitOtherClip 


BitOtherClip  (Apple,  C64,  ci28) 


graphics 


Function:       Special  version  of  BitmapCIip  that  allows  the  compacted  bitmap  data  to  come 
from  a  source  other  than  memory  (e.g.,  from  disk). 

Parameters:    rO        BUFFER  —  pointer  to  a  1 34-byte  buffer  area  (word). 

rlL       XPOS  —  x-position  in  bytes:  pixel j)osition  /8  (byte), 
r  1 H      Y  —  y-coordinate  (byte). 

r2L  W_WIDTH  —  width  in  cards  of  clipping  window:  pixeLwidth/8 
(byte). 

r2H      W^HEIGHT  —  height  in  pixels  of  clipping  window  (byte). 

rllL     DXl  —  delta-xl:  offset  of  left  edge  of  clipping  window  in  cards  from 

left  edge  of  full  bitmap  (byte), 
rl  IH    DX2  —  delta-x2:  offset  of  right  edge  of  clipping  window  in  cards  from 

right  edge  of  full  bitmap  (byte). 
rl2      DYl  —  delta-yl:  offset  of  top  edge  of  clipping  window  in  pixels  from 

top  edge  of  fiill  bitmap  (word), 
r  1 3       APPINPUT  —  pointer  to  application-defined  input  routine.  Called  each 

time  a  byte  from  a  compacted  bitmap  is  needed;  data  byte  is  returned  in 

the  a-register. 

rl4  SYNC  —  pointer  to  synchronization  routine.  Called  after  each  bitmap 
packet  is  decompressed.  Due  to  improvements  in  BitOtherClip,  this 
routine  need  only  consist  of  reloading  rO  with  the  BUFFER  address. 

where  the  upper-left  corner  of  the  clipped  bitmap  (the  window)  is  placed  at 
(XP0S*8,  Y).  The  lower-right  corner  is  at  ([XPOS*8]+[WJVIDTH*8], 
Y^WJiEIGHT). 

Uses:  dispBufferOn: 

bit?  — write  to  foreground  screen  if  set. 
bit  6  —  write  to  background  screen  if  set 

Returns:  nothing. 

Destroys:       a,  x,  y,  r0-rl2,  and  the  134-byte  buffer  pointed  at  by  rO. 

Description :  BitOtherClip  allows  the  application  to  decompress  and  display  a  bitmap  without 
storing  the  compressed  bitmap  in  memory.  Call  BitOtherClip  witii  the  address 
of  an  input  routine  (APPINPUT).  Each  time  BitOtherClip  needs  another  byte, 
it  calls  this  routine.  The  APPINPUT  routine  is  expected  to  read  data  from  the  disk 
or  some  other  device  and  return  a  single  byte  each  time  it  is  called. 

The  basic  width,  height,  position,  and  clipping  window  parameters  the  same  as 
those  for  BitmapCIip.  Refer  to  the  documentation  of  that  routine  for  more 
information. 

BitOtherClip  calls  the  user-supplied  APPINPUT  routine  until  it  has  enough 
bytes  to  form  one  bitmap  packet.  APPINPUT  must  preserve  r0-rl3  and  return 
the  data  byte  in  the  accumulator.  A  typical  APPINPUT  routine  saves  any  registers 
it  might  destroy,  calls  ReadByte  to  get  a  byte  from  a  disk  file,  places  die  byte  in 
the  BitOtherClip  buffer  (pointed  at  by  rO),  then  returns,  as  illustrated  in  the 
following  example. 
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128: 
Apple: 

Note: 
Example: 
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App Input : 


PushW 

1^1  1 

•save  rl,  r4,  and  r5 

PushW 

•   (saved  for  calls  to  ReadByte  routine 

irUSnrr 

TO  t 

Movew 

saveRl r  rl  i 

•  rl  <-  saveRl 

no  vcn 

savcKOf  ro 

•  r5  <—  saveRS 

liOaQn 

r4 , fdiSKQlKBut  1 

•  r4  <-  disk  buffer  we  use 

jsr 

MyReadByte  < 

•  get  a  byte  from  the  file 

*   (oyte  Is  in  A) 

Sua 

error  ^ 

•  save  any  error 

i  ^     1  ADD  T  V \ 

•  Apple  needs  to  use  buffer  pointer 

sua 

*  that  is  on  Alt  zero^page 

lay 

A  6  n  n 

#900  , 

'  null  inalrectlon  index 

sta 

(rO),y 

•  store  byte  into  buffer 

.if  (APPLE) 

'  Apple  needs  to 

sta 

ALTZP_OFF 

•  restore  normal  zero-page 

.endif 

MoveW 

r5,saveR5  < 

•  r5  ->  saveRS 

MoveW 

rl^saveRl  , 

•  rl  ->  saveRl 

PopW 

r5 

•  restore  rl,  r4,  and  r5 

PopW 

r4 

PopW 

rl 

rts 

•  exit 

When  BitOtherCiip  detects  a  complete  packet,  it  uncompacts  the  data  from  the 
buffer  to  the  screen.  After  the  bitmap  packet  has  been  uncompacted, 
BitOtherCiip  calls  the  SYNC  routine  supplied  by  the  caller.  The  SYNC  routine 
prepares  the  bitmap  buffer  for  the  next  packet  by  reloading  rO  with  the  address  of 
BUFFER  and  performing  an  rts. 

Sync: 

LoadW       rO, #ClipBuf fer  ;  reset  the  pointer 

rts  /  exit 

Under  GEOS  128,  OR'ing  DOUBLE^B  into  the  and  W^WIDTH 

parameters  will  automatically  double  the  x-position  and  the  width  (respecitvely)  in 
80-column  mode. 

DOUBLE  B  can  be  OR'ed  into  the  WIDTH  paramter  to  double  the  bitmap 
width  andlNAUX  B  can  be  OR*ed  into  the  XPOS  parameter  to  specify 
auxiliary  memory.  Also  on  Apple  GEOS,  the  APPINPUT  routine  must  use  the 
alternate  zero-page  version  of  rO  to  index  into  BitOtherClip*s  compaction 
buffer. 


.if  (APPLE) 
sta 
Idy 
sta 
sta 

.endif 


ALTZP_ON 
#$00 
(rO),y 
ALTZP  OFF 


Apple  needs  to  use  buffer  pointer 
that  is  on  Alt  zero-page 
null  indirection  index 
store  byte  into  buffer 
restore  normal  zero-page 


Do  not  pass  a  value  of  $00  for  either  the  WJVIDTH  or  WJIEIGHT  parameters. 


*♦*  CONSTANTS  *** 

NO  PICTURE        «  -1  ;  no  picture  error.  MUST  BE  NON-ZERO 

;window  coordinates  and  dimensions 


BitOtherClip 


WIN_CRDX  =  5 

WIN_CRDWIDTH  =  12 

WIN^Y  =40 

WIN  HEIGHT  =  110 


card  x-position 
card  width 
y-position 
height 


***  VARIABLES 

.ramsect 

saveRl 

saveRS 

leftOff set 

topOf fset 

picWidth 

picLength 

ClipBuffer 

.psect 


.block 
.block 
.block 
.block 
.block 
.block 


.block  135 


DrawPhoto 
DESCRIPTION: 


temp  save  for  GEOS  registers  that  need  to 

be  preserved  between  calls  to  ReadByte 
scroll  x-index  into  bitmap 
scroll  y-index  into  bitmap 
bitmap  card  width 
bitmap  card  height 
BitOtherClip  buffer  (+1  for  safety) 


PASSED: 


RETURNS: 


Reads  a  picture  in  from  a  photo  album  record  and  draws  it 
clipped  to  a  window.  Scroll  values  allow  a  specific  portion 
of  the  bitmap  to  be  shown. 

Open  VLIR  album  file  with  photo  scraps  in  records 
curPhoto         record  to  use 
leftOffset     scroll  value  on  x 
topOffset       scroll  value  on  y 


picWidth 
picLenght 

X 


from  photo  record 
from  photo  record 
error 


DrawPhoto: 


99$: 


jsr 

ClearWindow 

/  clear  the  drawing  window 

jsr 

GetPicSize 

;  get  the  size  of  the  picture 

txa 

;  check  for  error 

bne 

99$ 

jsr 

SetUpPhoto 

;  set  up  clipping  parameters 

/  carry  comes  back  set  if  we  can 

Idx 

#NO_ERROR 

/  no  errors  yet 

bcc 

99$ 

;  skip  drawing  if  necessary 

jsr 

PutUpPhoto 

;  draw  photo  from  the  record 

rts 

;  exit  with  error  in  x 

•  *  it  it*  ^r  it  it  ii*iiit*it       it  ******  It*  Ir**  it*  *  It  ir**ii  it -kit  It  It*  ******  it*  it* 

; ClearWindow 

/DESCRIPTION:  Erase  the  window  areas  where  we  plan  to  put  the  bitmap 

/PASS:  Nothing 

/RETURNS:  curPattern     »  0 

/DESTROYS:         CBM:  a,  x,  y,  r5-r8,'  rll 

APPLE:  a,  x,  y,  rll 

******************************* ********************************* 

ClearWindow: 

LoadB       curPattern, #0  /use  blank  fill  pattern 

jsr  i_Rectangle 
.byte  WIN_Y 
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.byte  (WIN_Y+WIN_HEIGHT) 

.word  {WIN_CRDX  *  8) 

.word  (WIN_CRDX*8  +  WIN_CRDWIDTH*8) 

rts 


SetUpPhoto 

DESCRIPTION:   Set  up  clipping  regions  and  other  parameters 


PASS: 


RETURNS: 


DESTROYS 
*********** 

SetUpPhoto: 


8$: 


15$: 


picWidth  card  width  of  bitmap 

picLength  height  of  bitmap 

leftOffset  card  scroll  index  into  bitmap 

rightOffset  line  scroll  index  into  bitmap 

carry  set  «  OK  to  draw 

clear  =  don't  draw  (lies  outside  of  region.) 
rO       BitOtherClip  buffer 
rlL     Card  x-position  of  window 
rlH     y-position  of  window 

r2L     number  of  cards  of  bitmap  to  display  in  window 
r2H     number  of  lines  of  bitmap  to  display  in  window 
rl2     lines  to  skip  on  top 
rllL  cards  to  skip  on  left 
rllH  cards  to  skip  on  right 


rO  <-  buffer  for  BitOtherClip » s  use 
rlL  <-  window's  card  x-position 
rlH  <-  window's  y-position 
A  <-  (picWidth-leftOffset) 

(difference  between  width  of 

picture  and  offset  into  picture) 
If  offset  exceeds  width,  then  skip 

over  picture  draw 

;  If  width  to  display  exceeds  width 

of  bitmap,  then  display  as  much  as 
;      will  fit  in  the  window. 

r2L  <-  card  width  to  display 

A  <-  (picLength-topOf f set) 

(difference  between  height  of 
picture  and  offset  into  picture) 

If  offset  exceeds  height,  then  skip 
over  picture  draw 

If  height  to  display  exceeds  height 
of  bitmap,  then  display  as  much  as 
will  fit  in  the  window. 

r2H  <-  pixel  height  to  display 

rl2  <-  lines  to  skip  on  top 
rllL  <-  cards  to  skip  on  left 


LoadW 

rO,  #ClipBuffer 

LoadB 

rlL,  WIN__CRDX 

LoadB 

rlH,  WIN_Y 

Ida 

picWidth 

sec 

sbc 

leftOffset 

bcc 

20$ 

beq 

20$ 

cmp 

#WIN  CRDWIDTH 

bcc 

8$ 

Ida 

#WIN_CRDWIDTH 

sta 

r2L 

Ida 

picLength 

sec 

sbc 

topOf f set 

bcc 

20$ 

beq 

20$ 

cmp 

#WIN  HEIGHT 

bcc 

15$ 

Ida 

#WIN_HEIGHT 

sta 

r2H 

MoveW 

topOf fset,rl2 

MoveW 

leftOffset, rllL 

Ida 

picWidth  - 

sec 

sbc 

r2L 

sbc 

leftOffset 

sta 

rllH 

rllH  <-  cards  to  skip  on  right 
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20$: 


clc 
rts 

sec 
rts 


flag  as  OK  to  draw 
exit 

flag  not  to  draw 


;PutUpPhoto 


/DESCRIPTION: 
/ 

/RETURNS: 
/ 

/DESTROYS: 


Draw  photo  from  record. 
X  error 
a,x,y,r0-rl5 


PutUpPhoto: 


99$: 


jsr 

GetPicSize  , 

reload  picture  length  and  width 

txa 

*  check  for  error  or  no  picture 

bne 

99$ 

leave  on  error 

jsr 

Sync  t 

•  rO  <-  clipBuffer 

LoadW 

rl3,  #AppInput  , 

•  rl3  <-  Applnput  routine 

LoadW 

rl2, #Sync 

•  rl2  <-  Sync  routine 

LoadB 

error, #NO_ERROR 

•  start  out  with  no  error 

jsr 

BitOtherclip 

?  display  photo 

Idx 

error 

?  put  any  error  into  x 

rts 

?  exit 

4r  4r  ********  * 


Applnput 


DESCRIPTION: 


APPLE: 


RETURNS : 


Applnput : 
PushW 
PushW 
PushW 
MoveW 
MoveW 
LoadW 
jsr 

stx 
.if  (APPLE) 

sta 
.endif 

Idy 

sta 
.if  (APPLE) 

sta 
.endif 

MoveW 

MoveW 


Bitmap  input  routine  called  by  BitOtherClip.  Returns  a  single 
byte  of  the  uncompacted  bitmap. 

This  routine  resides  in  main  memory  on  the  Apple,  so  the 
ClipBuffer  should  also  be  in  main  memory. 

bitmap  byte  in  BitOtherClip* s  buffer  (off  of  rO) 
any  error  in  error 

r************************************************************** 


rl 
r4 
r5 

saveRl, rl 
saveR5,  r5 
r4,#diskBlkBuf 
MyReadByte 

error 

ALTZP_ON 

#$00 
(rO),y 

ALTZP__OFF 

r5, saveRS 
rl, saveRl 


save  rl,  r4,  and  r5 


rl  <-  saveRl 
r5  <-  saveRS 

r4  <-  disk  buffer  we  use 
get  a  byte  from  the  file 
(byte  is  in  A) 
save  any  error 

Apple  needs  to  use  buffer  pointer 
that  is  on  Alt  zero-page 

null  indirection  index 
store  byte  into  buffer 
Apple  needs  to 
restore  normal  zero-page 

r5  ->  saveRS 
rl  ->  saveRl 
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PopW  r5 

PopW  r4 

PopW  rl 
rts 


restore  rl,  r4,  and  r5 


exit 


;Sync 

.*****★*★**★**«★★★*****★***★*************★★**★*****************« 

/DESCRIPTION:    Dumb  synchronization  routine  needed  by  BitOtherClip 

; 

Sync: 

LoadW       rO,#ClipBuffer  ;  reset  the  pointer 

rts  ;  exit 


/GetPicSize 

. ********************************************************************* 

/DESCRIPTION:    Get  picture  size  and  other  misc.  setup  for  PutUpPhoto 
; 

•RETURNS:  X  error 


GetPicSize: 


PushW 

rl 

save  rl  and  r4 

PushW 

r4 

Ida 

curPhoto  ; 

get  current  photo's  record  number 

jsr 

PointRecord  ; 

point  to  that  record 

rl  <-  block#  of  first  record 

Ida 

rlL  ; 

make  sure  there's  something  there 

.if 

(APPLE) 

ora 

rlH 

(check  both  bytes  on  Apple) 

.endif 

bne 

10$ 

branch  if  valid  record  found 

Idx 

#N0  PICTURE 

'  otherwise,  flag  no  picture 

Following 

line  changed  to  save  bytes   

bra 

40$ 

'  and  exit 

bne 

40$ 

•  unconditional  (NO__PICTURE  !=  0) 

10$: 

jsr 

SetUpReadByte 

r  prepare  for  ReadByte 

txa 

?  check  status 

bne 

40$ 

?  exit  on  error 

jsr 

ReadSizeBytes 

?  read  the  size  bytes  out  of  the  record 
?  and  store  them  in  the  photo  size 
;  variables  (error  comes  back  in  x) 

MoveW 

rl, saveRl 

;  save  off  rl  and  r5 

MoveW 

r5, saveRS 

• 

Following  line  removed  to  let 

error  propagate  back   

Idx 

#NO_ERROR 

;  we  got  this  far,  no  errors  found... 

40$: 

PopW 

r4 

;  restore  r4  and  r5 

PopW 

r5 

rts 

;  exit 

******* ************************************** ******** 

SetUpReadByte 

********** ********************************** ****** ************************* 

DESCRIPTION:   Set  up  variables  and  stuff  for  ReadByte 

STRATEGY: 

Special  case  Apple  because  it  requires  an  extra  step.  The  first  block  in 
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an  Apple  VLIR  record  is  actually  an  index  block  with  pointers  to  all  the 
other  blocks  in  the  chain.  We  read  this  block  into  the  aux  memory  buffer 
INDEXBLOCKBUF  so  ReadByte  has  something  to  work  with  (this  requires  that 
ReadByte  be  called  from  aux  memory  using  JsrToAux) .  The  general  disk 
buffer  diskBlkBuf  is  used  for  the  intermediate  blocks  since  it  is  in 
high  aux  memory  and  is  always  visible  (thus  eliminating  the  need  to 
set  RWbank) . 


PASS: 


RETURNS: 


APPLE:  rl  block  number  of  chain's  index  block 

CBM:  rlL, rlH  Track/sector  of  first  block  in  chain 

rl,  r4,  r5  set  up  for  ReadByte 
X  =  error  code 


DESTROYS:         a,  y 

SetUpReadByte: 
.if  (APPLE) 

LoadW 

LoadB 

jsr 


It***********************-* 


LoadB 
.else  ; (CBM) 

Idx 
.endif 

MoveW 

LoadW 

Ida 

sta 

sta 

rts 


r 4, # INDEXBLOCKBUF 
RWbank, #AUX 
GetBlock 

RWbank, #MAIN 

#NO_ERROR 

r4,rl 

r4, diskBlkBuf 

#0 

r5L 

r5H 


r4  <-  buffer  for  index  block 
set  disk  read  to  proper  bank 
read  in  the  chain's  index  block 
(error  now  in  x) 
restore  disk  bank  to  normal 

no  error  on  CBM 

rl  <-  track/sector  of  1st  block  (CBM) 

<-  index  block  pointer  (APPLE) 
r4  <-  disk  buffer  for  ReadByte 
r5  <-  $0000  (for  ReadByte) 


exit  with  error  in  X 


MyReadByte 
D-ESCRIPTION: 


PASS: 

RETURNS : 

DESTROYS: 

MyReadByte : 

.if  (APPLE) 
Ida 
Idx 
jsr 

.else  ; (CBM) 
jsr 


My  version  of  ReadByte  that  deals  with  all  machine  weirdness. 
This  routine  expects  to  use  the  general-purpose  disk  buffer  at 
diskBlkBuf  because,  since  it  is  in  high-aux  on  the  Apple,  it 
avoids  the  bank  switching  complications. 

Call  wherever  you  would  normally  call  ReadByte.  Call 
SetUpReadByte  to  set  the  proper  parameters  prior  to  calling. 

This  would  make  a  good  Macro. 

Same  as  ReadByte 

Same  as  ReadByte 

Same  as  ReadByte 

******:r^*******************«**4r  ********************************* 


# [ReadByte 
#] ReadByte 
JsrToAux 


ReadByte 


APPLE 

Call  ReadByte  from  aux  memory 
so  that  the  aux  memory 
INDEXBLOCKBUF  is  visible 

;  CBM 

;  just  use  normal  ReadByte 
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.endif 

rts  ;  exit 


Reads! zeBytes 

DESCRIPTION:   Read  in  the  first  three  bytes  from  the  current  record  and 
store  them  in  the  size  variables. 

PASS:  File  open  and  system  ready  for  calls  to  ReadByte. 

RETURNS:  rl,   r4,  r5  ready  for  ReadByte  calls  to  load  bitmap  data 

X  error 
picWidth        card  width  of  bitmap 
picLength       line  height  of  bitmap 

DESTROYS:         a,  y 

*«********************************************************« ************ 

ReadSizeBytes : 


99$: 


jsr 
sta 
txa 
bne 
jsr 
sta 
txa 
bne 
jsr 
sta 

rts 


MyReadByte 
picWidth 

99$ 

MyReadByte 
picLength 

99$ 

MyReadByte 
picLength+1 


get  photo  width 
check  for  error 
get  photo  length  (low  byte) 
check  for  error 
get  photo  length  (high  byte) 

exit  error  in  x 
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BldGDirEntry  (Apple,  C64,  cns) 


mid-level  disk 


Function: 


Parameters: 


Returns: 

Alters: 
Destroys: 


Description: 


Apple: 


Example: 


Builds  a  directory  entry  in  memory  for  a  GEOS  file  using  the  information  in  a  file 
header.  Apple  GEOS  version  can  also  build  an  entry  for  a  folder  (subdirectory). 


r6 


Commodore: 

r2        NUMBLOCKS  —  number  of  blocks  in  file  (word). 

TSTABLE  —  pointer  to  a  track/sector  list  of  unused  blocks  (unused  but 
allocated  in  the  BAM),  usually  a  pointer  to  fileTrScTab;  BlkAlIoc 
can  be  used  to  build  such  a  list  (word). 
FUJEHDR  —  pointer  to  GEOS  file  header  (word). 


r9 

Apple: 
r2 

r6 


r7 
r8 
r9 


NUMBLOCKS  —  number  of  blocks  in  file  or  $0000  to  create  a 
subdirectory  (word). 

INDXBLK  —  if  creating  a  file,  block  number  of  sequential-file  index 
block  or  VLIR  master  index  block;  if  creating  a  subdirectory,  key  block 
number  for  subdirectory  (word). 
FUJEB  YTES  —  number  of  bytes  in  file  (word). 
HDBLKNUM  —  block  number  of  the  file's  header  block  (word). 
FILEHDR  —  if  creating  a  file,  pointer  to  GEOS  file  header,  if  creating  a 
subdirectory,  pointer  to  null-terminated  name  for  the  subdirectory  (up 
15  characters  plus  a  NULL);  must  be  in  main  memory,  (word). 

Commodore: 

r6  pointer  to  first  non-reserved  block  in  track/sector  table  (BidGDirEntry 
reserves  one  block  for  the  file  header  and  a  second  block  for  the  index 
table  if  the  file  is  a  VLIR  file). 

dirEntryBuf       contains  newly-built  directory  entry. 

Commodprg: 
a,  X,  y,  rlH. 

Apple: 

a,  X,  y,  r3. 

Given  a  GEOS  file  header,  BidGDirEntry  will  build  a  system  specific  directory 
entry  suitable  for  writing  to  an  empty  directory  slot.  BidGDirEntry  takes  care 
of  differences  between  Apple  and  Ctommodore  GEOS. 

Most  applications  create  new  files  by  calling  SaveFile.  SaveFile  calls 
SetGDirEntry,  which  calls  BidGDirEntry  as  part  of  its  normal  processing. 

The  Apple  version  of  BidGDirEntry  can  also  be  used  to  build  subdirectory 
entries  by  passing  $00(X)  in  r2.  The  easiest  way  to  create  a  subdh-ectory  is  to  call 
MakeSubDir. 


.************************************ *************************************** 

;MySetGDirEntry  (My  Version  of  Set  Geos  Directory  Entry) 


;  This  routine  duplicates  the  function  of  the  Kernal's  SetGDirEntry  for 
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demonstration  purposes.  It  shows  examples  of  the  following  routines: 

BldGDirEntry 
GetFreeDirBlk 
UpdateParent 
PutBlock 

PASS:  Same  as  SetGDirEntry 

DESTROYS:         Same  as  SetGDirEntry 


.if  (APPLE) 
DIRCOPYSIZE 
.else  (CBM) 
DIRCOPYSIZE 
.endif 


=  39 
=  30 


bytes  in  directory  to  copy  over 
after  BldGDirEntry  is  called 


MySetGDirEntry : 


jsr 

BldGDirEntry  ; 

build  directory  entry  for  GEOS  file 

jsr 

GetFreeDirBlk  / 

get  block  with  free  directory  entry 

r3  =»  1st  byte  of  free  entry 

block  number  of  block  in  rl 

txa 

test  for  error  code 

bne 

90$  ; 

if  error,  exit . . . 

.if  (APPLE) 

MoveW 

r3,r5  ; 

make  r5  point  to  directory  entry 

.else  ; (CBM) 

tya 

get  offset  into  diskBlkBuf  for  dir  entry 

clc 

adc 

#[diskBlkBuf 

and  get  absolute  address  in  buffer 

sta 

rSL 

Ida 

#ldiskBlkBuf 

adc 

#0 

(propagate  carry) 

sta 

r5H 

.endif  ;  (else 

CBM) 

•   (r5  =  pointer  to  dir  entry  in  buffer) 

Idy 

#DIRCOPYSIZE 

•  copy  over  some  bytes 

10$: 

Ida 

dirEntryBuf ,y 

get  byte  from  directory  entry  built 

sta 

(r5) ,y 

•  store  new  entry  into  block  buffer 

dey 

bpl 

10$ 

?  loop  till  copied 

jsr 

TimeStampEntry 

?  stamp  the  dir  entry  with  time  &  date 

LoadW 

r4,#diskBlkBuf 

;  write  out  the  new  directory  entry 

jsr 

PutBlock 

txa 

;  get  error  status 

bne 

90$ 

;  if  error,  exit 

.if  (APPLE) 
PushW 

Ida 
jsr 
PopW 


rl 

#(INC_NUM_FILES 

UpdateParent 

rl 


Update  parent  directory  on  Apple 
save  block  number  of  directory  block  that 
this  file  entry  is  stored  in 
MOD_DATE) 

update  parent  directory's  directory  entry 
restore  block  number  of  directory  block 

that  this  file  entry  is  saved  on 
(error  status  now  in  x) 


.endif  ; (APPLE) 
90$: 

rts 


************* ****************************************************** ******** 

TimeStampEntry 

Add  time/date  stamp  to  directory  entry 
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TimeStampEntry : 


.if   (C64  1 

1   C128)                COMMODORE  *** 

TDSIZE 

number  of  bytes  in  time/date  entry 

Idy 

fOFF__YEAR  ; 

otrset  to  time/aate  stamp 

10$: 

Ida 

year-OFF_^YEAR,  y  ; 

get  the  yr/mo/day/hr/min 

sta 

Cro) , y  ; 

store  in  dir  entry 

iny 

cpy 

Jtorr   VT  A D j-Tne  T T 

ffUr  r  __ILAr\+iUbi^hj  / 

done  yet? 

bne 

1    V  1 

if  not,  loop 

rts 

.else  ; (APPLE) 

•www  ArrLL 

clc 

stamp  creation  date 

jsr 

StampTimeDate  i 

sec 

stamp  moaiiicatlon  date 

jsr 

StampTimeDate  , 

rALL  inKUUUn  to  ot ampTimeDate 

/  rts 

StampTimeDate: 

(carry  indicates  stamp  to  modify) 

Ida 

minutes  « 

get  minutes  (0—59) 

Idy 

tOFF__FCTIME  , 

•  get  offset  to  creation  minutes 

bcs 

110$  1 

if  stamping  creation  time,  skip 

Idy 

fOFF__FMTIME  i 

get  offset  to  modification  minutes 

110$: 

sta 

(r5),y  , 

'  save  hours  in  directory  entry . 

Ida 

hour  1 

'  get  hours  (0-23) 

iny 

'  get  offset  to  hours 

sta 

» 

(ro) , y  , 

•  save  minutes  in  directory  entry 

idy 

fOr r_rCDATE  i 

get  or t set  to  mmmdaaaa 

bcs 

X  ^  U  V 

*  if  stamping  creation  time,  skip 

Idy 

120$: 

Ida 

mont"  h 

f    geu  niunL.n    yx  ±£} 

asl 

asl 

asl 

a 

asl 

a 

asl 

a 

?  carry  holds  month's  msb 

ora 

day 

;  combine  with  day  to  get  mmmddddd 

sta 

(r5),y 

;  save  mmmddddd 

iny 

;  get  offset  to  yyyyyyym 

Ida 

year 

;  get  year 

rol 

a 

;  carry  has  m's  MSB;  move  it  into 

;          LSB  to  get  yyyyyyym 

sta 

(r5),y 

;  save  yyyyyyym 

rts 

;  exit 

.endif  ; ( .else  APPLE) 


See  also:  SetGDirEntry. 
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BlkAUoC  (Apple,  C64,  C128) 


mid-level  disk 


Function:       Allocate  enough  disk  blocks  to  hold  a  specified  number  of  bytes. 


Parameters:  r2 


Uses: 


Returns: 


BYTES  —  number  of  bytes  to  allocate  space  for.  Commodore  version 
can  allocate  up  to  32,258  bytes  (127  CiDmmodore  blocks);  Apple 
version  can  allocate  up  to  65,535  ($ffff)  bytes  (128  ProDOS  blocks) 
(word). 


Commodore: 

r6         TSTABLE  —  pointer  to  buffer  for  building  out  track  and  sector  table  of 
allocated  blocks,  usually  points  to  fileTrScTab  (word). 


curDrive 

Commodore: 

curDlrHead 

dir2Headt 

dirSHeadt 

interleave^ 


Applg: 

VBMBlknot 

numVBMBlkst 

curVBlknot 
VBMchangedt 


currently  active  disk  drive. 


this  buffer  must  contain  the  current  directory  header. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 

desired  physical  sector  interleave  (usually  8);  used  by 
setNextFree.  Applications  need  not  set  this  explicitly  — 
will  be  set  automatically  by  internal  GEOS  routines. 


Apple  GEOS  BIkAlloc  starts  searching  for  free  blocks 
beginning  with  the  block  that  follows  the  last  VBM  block, 
the  block  following  the  last  VBM  block  is  found  by  adding 
the  value  in  numVBMBlks  to  the  value  in  VBMBlkno. 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
X         error  ($00  =  no  error). 

r2        number  of  blocks  allocated  to  hold  BYTES  amount  of  data. 


Commodore: 

rSL  track  of  last  allocated  block, 
r 3  H      sector  of  last  allocated  block. 


Apple; 
r3 


last  block  allocated. 


Alters: 


Commodore: 
curDirHead 
dir2Headt 
dir3Headt 

Applg; 

curVBlknot 
VBMchangedt 


BAM  updated  to  reflect  newly  allocated  blocks. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


used  by  VBM  cacheing  routines. 

set  to  TRUE  by  VBM  cacheing  routines  to  indicate  cached 
VBM  block  has  changed  and  needs  to  be  flushed 
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^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 

Destroys:  Commodore: 
a,  y,  r4-r8. 

Apple; 

a,  y,  r4,  r6,  r7,  r8H. 

Description:  BIkAlloc  allocates  enough  blocks  on  the  disk  for  BYTES  amount  of  data.  The 
GEOS  SaveFile  and  WriteRecord  routines  call  BIkAlloc  to  allocate  multiple 
blocks  prior  to  calling  WriteFile.  Most  applications  do  not  call  BIkAlloc 
direcdy,  but  rely,  instead,  on  the  higher-level  SaveFile  and  WriteRecord. 

BIkAlloc  calculates  the  number  of  blocks  needed  to  store  BYTES  amount  of 
data,  taking  any  standard  overhead  into  account  (such  as  the  two-byte  track/sector 
link  required  in  each  Commodore  block),  then  calls  CalcBlksFree  to  ensure  that 
enough  free  blocks  exist  on  the  disk.  If  there  are  not  enough  free  blocks  to 
accomodate  the  data,  BIkAlloc  returns  an  INSUFFICIENT^SPACE  error 
without  allocating  any  blocks.  Otherwise,  BIkAlloc  calls  SetNextFree  to 
allocate  the  proper  number  of  unused  blocks. 

C64  &  C128:  The  Commodore  version  of  BIkAlloc  builds  out  a  track  and  sector  table  in  the 
buffer  pointed  to  by  TSTABLE.  The  256  bytes  at  fileTrScTab  are  usually  used 
for  this  purpose.  When  BIkAlloc  returns,  the  table  contains  a  two-byte  entry  for 
each  block  that  was  allocated:  the  first  byte  is  the  track  and  the  second  byte  is  the 
sector.  The  last  entry  in  the  table  has  its  first  byte  set  to  $00,  indicating  the  end  of 
the  table.  The  second  byte  of  the  last  entry  is  an  index  to  the  last  byte  in  the  last 
block.  This  track/sector  list  can  be  passed  directiy  to  WriteFile  for  use  in  writing 
data  to  the  blocks. 

BIkAlloc  does  not  automatically  write  out  the  BAM.  See  PutDirHead  for  more 
information  on  writing  out  the  BAM.  BIkAlloc  does  not  allocate  blocks  on  the 
directory  track.  Refer  to  GetFreeDirBlk  for  more  information  on  allocating 
directory  blocks. 

Apple:  The  Apple  version  of  BIkAlloc  builds  out  a  list  of  allocated  blocks  in  the  internal 

INDEXBLOCKBUF  buffer.  This  index  block  is  a  modified  512-byte  ProDOS 
sapling  index  block.  The  block  is  divided  into  two  256-byte  portions.  The  lower 
half  (bytes  0  through  255)  represent  the  low-bytes  of  the  data  blocks  and  the 
upper  half  (bytes  256  through  511)  represent  the  associated  high-bytes.Byte  0 
and  byte  256+0  combine  to  form  the  block  number  of  the  first  data  block,  byte  1 
and  byte  256+1  combine  to  form  the  number  of  the  second  data  block,  and  so  on 
for  each  allocated  block.  A  block  pointer  of  $0000  ($00  high,  $00  low)  represents 
the  end  of  the  list 

The  last  two  pointers  in  the  index  block — the  ones  in  a  standard  ProDOS  sapling 
index  that  point  to  the  254tii  and  255th  blocks  in  the  chain — comprise  a  four-byte 
size  value  in  GEOS.  The  four-byte  value,  which  represents  the  number  of  bytes 
stored  in  the  allocated  blocks,  can  be  accessed  using  the  following  offsets  into  the 
index  block: 

DSIZEO  Low  byte 

DSIZEl 
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DSIZE2 

DSIZE3  High  byte 

BIkAlIoc  does  not  patch  the  size  information  into  INDEXBLOCKBUF.  The 
application  must,  therefore,  do  this  itself  before  writing  the  index  block  to  disk. 
However,  because  INDEXBLOCKBUF  is  in  auxiliary  memory,  applications 
cannot  patch  the  index  block  direcdy  from  main  memory.  MoveAuxData  can 
transfer  the  5 12  bytes  from  auxiliary  to  a  buffer  visible  from  main  memory. 


LoadW        rO,   # INDEXBLOCKBUF    /  copy 

LoadW       rl,  tdliskBlkBuf  /  to  t 

LoadW        12,   #BLOCKSIZE  ;  move 

Ida           #AUXtoMAIN  ;  copy 

jsr  MoveAuxData  ; 

The  size  information  can  then  be  patched 
the  last  two  block  pointers. 


from  index  blk 
imp  buffer 
a  full  block 
aux  to  main 


into  the  index  block,  masquerading  as 


MoveB  dataSize+0,diskBlkBuf +DSIZEO  ;  transfer  size  bytes 

MoveB  dataSize+l^diskBlkBuf+DSIZEl  ;   (low  to  high  order) 

MoveB  dataSize+2,diskBlkBuf+DSIZE2  ; 

MoveB  dataSize+3,diskBlkBuf+DSIZE3 


The  block  can  then  be  transferred  back  to  INDEXBLOCKBUF. 


LoadW  rO,   #diskBlkBuf  ;  copy  from  buffer 

LoadW  rl,   # INDEXBLOCKBUF  ;  back  to  index  block 

LoadW  t2,  #BL0CKSIZE  ;  move  a  full  block 

Ida  #MAINtoAUX  ;  copy  main  to  aux 

jsr  MoveAuxData  ; 


Use  the  index  block  to  write  out  the  appropriate  data,  perhaps  by  calling 
WriteFile,  then  use  PutBIock  to  write  out  the  index  block  to  a  previously 
allocated  block. 


MoveW  yourlndex^rl  ;  where  to  write  block  (you  suppy) 

LoadW  tA,  # INDEXBLOCKBUF  ;  where  data  is 

LoadB  RWbank,  #AUX  ;  bank  to  aux 

jsr  PutBIock  /  write  out  block 

LoadB  RWbank,  #MAIN  ;  back  to  main 


BlkAlloc  does  not  flush  the  VBM  cache.  See  PutVBM  for  more  information  on 
flushing  the  cache. 

Note:  For  more  information  on  the  scheme  used  to  allocate  successive  blocks,  refer  to 

SetNextFree. 


Example: 


GrabSomeBlocks : 

LoadW*  r2,#BUF_SIZE 
.if   (C64   I  I  C128) 

LoadW       r6, #f ileTrSecTab 


.endif 

jsr 
txa 
bne 


BlkAlloc 
99$ 


number  of  bytes  to  allocate 

CBM  needs  buffer  to  build  out  table 
of  links.  APPLE  will  automatically  use 
INDEXBLOCKBUF 

allocate  the  blocks 

check  status 

and  exit  on  error 
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;         more  code  here 

99$:   rts  ;exit 
.ramsect 

K                        «  1024  ;. one  kilobyte 

buffer":              .block            5*K  ;  5K  buffer 

BUF_SIZE           =  (*-buffer)+l  ;  size  of  buffer 
•psect 

For  a  more  detailed  example,  see  WritFile. 

See  also:        NxtBlk Alloc,  SetNextFree,  GetFreeDirBlk,  FreeBIock. 
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BlOCkPrOCeSS   (Apple,  C64,  C128) 


process! 


Function: 
Parameters: 

Returns: 

Destroys: 

Description: 


Note: 
Example: 


Block  a  processes  events, 

X  PROCESS  —  process  to  block  (0  to  n-1,  where  n  is  the  number  of 

processes  in  the  table)  (byte)- 

X  unchanged. 

a 

BlockProcess  causes  MainLoop  to  ignore  the  runable  flag  of  a  particular 
process  so  that  if  a  process  timer  reaches  zero  (causing  the  process  to  become 
runable)  no  process  event  is  generated  until  the  process  is  subsequently 
unblocked  with  a  call  to  UnblockProcess.  BlockProcess  stops  the  process  at 
the  MainLoop  level.  Refer  to  FreezeProcess  to  stop  the  process  at  the  Interrupt 
Level. 

BlockProcess  does  not  stop  the  countdown  timer,  which  continues  to 
decrement  at  Interrupt  Level  (assuming  the  process  is  not  frozen).  When  the  timer 
reaches  zero,  the  runable  flag  is  set  and  the  timer  is  restarted.  As  long  as  the 
process  is  blocked,  though,  MainLoop  ignores  this  runable  flag  and,  therefore, 
never  generates  an  event.  When  a  blocked  process  is  later  unblockeki,  MainLoop 
checks  the  runable  flag.  If  the  runable  flag  was  set  during  the  time  the  process 
was  blocked,  this  pending  event  generates  a  call  to  the  appropriate  service 
routine.  Only  one  event  is  generated  when  a  process  is  unblocked,  even  if  the 
timer  reached  zero  more  than  once. 

If  a  process  is  already  blocked,  a  redundant  call  to  BlockProcess  has  no  effect. 


SuspendClock: 
Idx 
jmp 


#CLOCK__PROCESS 
BlockProcess 


X  <-  process  number  of  the  clock 
block  that  parictular  process 


See  also: 


UnblockProcess,  FreezeProcess. 
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BMult 
mathl 


Function: 
Parameters: 

Returns: 

Destroys: 
Description: 

Note: 

Example: 

SeeAIso: 


Unsigned  word-by-byte  multiply:  multiplies  an  unsigned  word  and  an  unsigned 
byte  to  produce  an  unsigned  word  result 

X  OPERANDI  —  zero-page  address  of  word  multiplicand  (byte  pointer  to 

a  word  variable). 

y  OPERAND2  —  zero-page  address  of  multiplier  (byte  pointer  to  a  word 
variable  —  use  a  word  variable;  only  the  low-byte  is  used  in  the 
multiplication  process,  but  the  high-byte  of  the  word  is  destroyed). 

Note:  result  =  OPERANDI  (word)  *  0PERAND2(byte). 

X,  y  unchanged. 

word  pointed  to  by  OPERANDI  has  its  high-byte  set  to  $00,  and  its  low-byte 
unchanged. 

word  pointed  to  by  OPERANDI  contains  the  word  result, 
a,  r6-r8. 

BMult  is  an  unsigned  word-by-byte  multiplication  routine  that  multiplies  the 
word  at  one  zero-page  address  by  the  byte  at  another  to  produce  a  16-bit  word 
result.  BMult  operates  by  clearing  the  the  high-byte  of  OPERANDI  and  calling 
DMult.  The  result  is  stored  as  a  word  back  in  OPERANDI. 

Because  r6,  r7  and  r8  are  destroyed  in  the  multiplication  process,  they  cannot  be 
used  to  hold  the  operands. 

Overflow  in  the  result  (beyond  16-bits)  is  ignored. 


Multiply  the  value  in  r9  by  87  and  store  the  result  back  in  r9 

(rl  is  destroyed) 

Idx  #r9  ;  point  to  OPERANDI  in  r9 

LoadB        rlL, #87  ;  rl  <-  87  (0PERAND2) 

Idy  #rl  /  point  to  0PERAND2  in  rl 

jsr  BBMult  /  r9  <-  r9  *  rlL 


BBMult,  DMult,  Ddiv,  DSdiv. 
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BoOtGEOS   (C64,  C128) 


internal  I 


Function: 
Parameters:  none. 
Returns: 
Destroys: 
Description 


Restart  GEOS  from  a  non-GEOS  application. 


Example: 


Does  not  return, 
n/a 


BootGEOS  provides  a  method  for  an  non-GEOS  to  run  in  the  GEOS 
environment — starting  up  from  die  deskTop  and  returning  to  GEOS  when  done. 
The  non-GEOS  application  need  only  preserve  the  area  of  memory  between 
BootGEOS  ($cOOO)  and  BootGEOS+$7f  ($c07f).  The  rest  of  the  GEOS 
Kemal  may  be  overwritten.  To  reboot  GEOS,  simply  jmp  BootGEOS,  which 
completely  reloads  the  operating  system  (either  from  disk  in  a  "boot"  procedure  or 
from  a  RAM-expansion  unit  in  an  "rboot"  procedure)  and  returns  to  the  GEOS 
deskTop. 

A  program  can  check  to  see  if  it  was  loaded  by  GEOS  by  checking  the  memory 
starting  at  $c006  (bootName)  for  the  ASCII  (not  CBMASCH)  string  "GEOS 
BOOT".  If  loaded  by  GEOS,  the  program  can  check  bit  5  of  $c012 
(sysFlgCopy):  if  this  bit  is  clear,  ask  the  user  to  insert  their  GEOS  boot  disk 
before  continuing,  otherwise  a  boot  disk  is  not  needed  because  GEOS  will  rboot 
from  die  RAM  expansion  unit.  To  actually  return  to  GEOS,  set  CPU  DATA  to 
$37  (KRNL  BAS  10  IN)  on  a  Commodore  64  and  set  config  to  $40 
(CKRNL  BAS  I(T  iK)  on  a  Commodore  128,  tiien  jump  to  BootGEOS 
($cOIO). 


BYTESTOSAVE 
RBOOT  BIT 


$80 
5 


;  no.  of  bytes  to  save  at  BootGEOS 
;  bit  in  sysFlgCopy  to  check 


OnEntry : 
Idx 

10$: 

Ida 
sta 
dex 
bne 
rts 
.ramsect 
GEOS__save 
.psect 


#BYTESTOSAVE 

BootGEOS-lr  X 
GEOS_save-l,x 

10$ 


.block  BYTESTOSAVE 


save  bytes  GEOS  needs  so  we  can  use  area 
START LOOP 

copy  a  byte 

count — 

if  (count  !«  0),  then  loop 
ENDLOOP 

save  area  for  GEOS  restart  block 


OnExit: 

.if  (C646&C128) 

.echo  Warning:  expected  both  C64  and  C128  constants  TRUE 
.endif 
Ida 
cmp 
bit 
Ida 
bpl 

128$: 

Ida 
sta 


version 
#$13 
64$ 

cl28Flag  ' 
64$ 

CKRNL_BAS__IO__IN 
config 


Get,  version  of  GEOS 

If  version  <  1.3,  then  branch 
Else,  test  for  GEOS  128 
If  GEOS64,  then  branch 

load  128  memory  mapping 
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bra 

200$ 

Ida 

#KRNL_BAS_IO  IN  , 

'  load  64  memory  mapping 

sta 

CPU_DATA 

Idx 

tBYTESTOSAVE 

•  restore  bytes  GEOS  needs 

to  restart 

'  STARTLOOP 

Ida 

GEOS_save-l, X 

•        copy  a  byte 

sta 

BootGEOS-l,x 

dex 

count — 

bne 

10$ 

if  (count  !=»  0) ,  then 

loop 

•  ENDLOOP 

Ida 

#(%1«RB00T_BIT) 

? check  for  Rboot  flag 

and 

sysFlgCopy 

bne 

99$ 

?  if  flag  is  clear,  branch 

to  rboot 

jsr 

AskForBootDisk 

•  else,  get  user  to  insert 

boot  disk 

jmp 

BootGEOS 

See  also:       Firstlnit,  StartAppI,  GetFile,  EnterDeskTop. 
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This  page  intentionally  left  blank  to  maintain  right/left  (verso/recto) 
page  ordering.  Final  version  will  correct  this. 


CalcBlksFree  (Apple,  C64,  ci28) 


mid-level  disk  I 


Function:       Calculate  total  number  of  free  blocks  on  disk. 

Parameters:  Commodore: 

rS        DIRHEAD  —  address  of  directory  header,  should  always  point  to 
curDirHead  (word). 

Apple: 
none. 


Uses: 


curDrive 

Commodore: 

dirZHeadt 

dirSHeadt 

Apple: 

curVBlknot 

VBMchangedt 

numVBMBIkst 


(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


Returns: 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
r4        number  of  free  blocks. 


Applg: 

X 


error  ($00  =  no  error). 


Commodore: 

rS  unchanged. 

r3  in  GEOS  vl.3  and  later:  total  number  of  available  blocks  on  empty  disk. 
This  is  useful  because  vl.3  and  later  support  disk  devices  other  than  the 
1541.  GEOS  versions  earlier  than  vl.3  leave  r3  unchanged. 


Destroys:       a,  y. 


Description:  CalcBlksFree  calculates  the  number  of  free  blocks  available  on  the  disk.  An 
application  can  call  CalcBlksFree,  for  example,  to  tell  the  user  the  amount  of 
free  space  available  on  a  particular  disk.  GEOS  disk  routines  that  allocate  multiple 
blocks  at  once,  such  as  Blk Alloc,  call  CalcBlksFree  to  ensure  enough  free 
space  exists  on  die  disk  to  prevent  a  surprise  INSUFFICENT^SPACE  error, 
midway  through  the  allocation.  (This  is  why  it  is  usually  not  necessary  to  check 
for  sufficent  space  before  saving  a  file  or  a  VLIR  record— die  higher  level  GEOS 
disk  routines  handle  this  checking  automatically.) 

C64  &  C128:  The  Commodore  version  of  CaclBlksFr6e  looks  at  the  BAM  in  memory  and 
counts  the  number  of  unallocated  blocks.  The  BAM  is  stored  in  the  directory 
header  and  the  directory  header  is  stored  in  the  buffer  at  curDirHead.  Calling 
CalcBlksFree  requires  first  loading  rS  with  the  address  of  curDirHead. 

LoadW       r5,   #curDirHead         ;  point  to  the  directory  header 
jsr  CalcBlksFree  ;  before  calling  CalcBlksFree 
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When  checking  the  total  number  of  blocks  (both  allocated  and  free)  on  a  particular 
disk  device,  call  CalcBlksFree  with  r3  loaded  with  the  number  of  blocks  on  a 
1541  disk  device.  On  GEOS  vL3  and  above,  this  number  is  changed  to  reflect 
the  actual  number  of  blocks  in  the  device.  On  previous  versions  of  GEOS,  r3 
comes  back  unchanged. 


Apple: 
Example: 


N1541_BLOCKS 
LoadW 
LoadW 
jsr 


=  664 

r3,  #N1541_BLOCKS 
r5,  #curDirHeacl 
CalcBlksFree 


total  number  of  blocks  on  1541  devices 
assume  1541  block  count  for  vl.2  Kernals 
point  to  the  directory  header 
r3  comes  back  with  total  number  of  blocks 
on  this  device 


The  Apple  version  of  CalcBlksFree  looks  through  the  VBM  blocks  on  the  disk 
Oarger  capacity  disks  may  have  more  than  one)  and  determines  the  number  of 
unallocated  blocks  by  counting  the  allocation  bits. 


CheckDiskSpace 

DESCRIPTION:    Ensures  that  the  current  disk  has  a  enough  space  for  a 
minimum  number  of  bytes.  Does  not  take  into  account  any 
index  blocks  or  other  blocks  needed  to  maintain  the  file 
structure.  Works  with  GEOS  64,  GEOS  128,  and  Apple  GEOS. 


r2       number  of  bytes  we  need 

X  =     error  if  any.  If  not  enough  space#  returns  an 
INSUFFICIENT_SPACE  error. 

a,  y,  r2,  r3,  r8,  r9 


PASSED: 
RETURNS: 

DESTROYED: 


;  Number  of  bytes  that  can  be  stored  in  each  block  on  the  disk.  Accounts  for 
;  two-byte  track/sector  link  on  Commodore  versions  of  GEOS. 
BLOCK  BYTES       =  BLOCK  SIZE- ( (C64 I  1 128) *2) 


CheckDiskSpace 

r2  «  #  of  BYTES  to  check  for 

Ida 

r2L 

check  if  zero  bytes  requested 

ora 

r2H  ; 

beq 

80$  ; 

if  so,  exit  with  no  error 

LoadW 

r3,#BL0CK  BYTES  ; 

r3  <-  number  of  bytes  per  block. 

Idx 

#r2  ; 

divide  r2  by  r3  to  get  number  of 

Idy 

#r3  ; 

blocks  to  hold  BYTES 

jsr 

Ddiv  ; 

r2  <-  r3/r2  ;  r8L  <-  remainder 

Ida 

r8L  ; 

Any  remainder  bytes? 

ora 

r8H 

beq 

5$ 

if  not,  OK 

IncW 

r2 

otherwise  1  more  block  needed 

5$: 

'  r2  «  BLOCKS  needed  to  hold  BYTES 
•  get  number  of  free  blocks  on  dis 

.if   (C64I IC128) 

•  CBM  GEOS  requires  extra  step 

LoadW 

r5,#curDirHead  , 

point  to  directory  header 

.endif 

jsr 

CalcBlksFree  , 

•  r4  <-  free  blocks  on  disk 

.if  (APPLE) 

•  APPLE  GEOS  must  error  check  here 

txa 

check  status 

bne 

100$ 

branch  to  exit  with  error... 

.endif 

Idx 

#INSUFFICIENT_SPACE 

;  assume  not  enough  space 

CmpW 

r2,r4 

•  are  there  enough  free  blocks? 

2 


CalcBlksFree 


80$: 


100$: 


bgt 


Idx 


rts 


100$ 

#N0  ERROR 


if  not,  asssump.  correct,  branch, 

otherwise,  no  error 

exit 


See  also: 


BIkAlloc,  SetNextFree,  FreeBlock. 
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CallRoutine 


ICallRoutine  (Apple,  C64,  cus) 


utility 


Function: 
Parameters: 

Returns: 

Destroys: 

Description: 


Note: 


Example: 


Perform  a  pseudo-subroutine  call,  checking  first  for  a  null  address  (which  will  be 
ignored). 

a  [ADDRESS  — low  byte  of  subroutine  to  call. 

X  ]  ADDRESS  —  high  byte  of  subroutine  to  call. 

where  ADDRESS  is  the  address  of  a  subroutine  to  call. 

depends  on  subroutine  at  ADDRESS. 

depends  on  subroutine  at  ADDRESS. 

CallRoutine  offers  a  clean  and  simple  way  to  perform  an  indirect  jsr  through  a 
vector  or  call  a  subroutine  with  an  address  from  a  jump  table.  Before  simulatin  a 
jsr  to  the  address  in  the  x  and  a  registers,  it  also  checks  for  a  null  address 
($0(XX)).  If  the  address  is  $(XXX)  (x=$00  and  a=$(X)),  CallRoutine  performs  rts 
without  calling  any  subroutine  address.  This  makes  it  easy  to  nullify  a  vector  or 
an  entry  in  a  jump  table  by  using  a  $(XXX)  value. 

GEOS  frequentiy  uses  CallRoutine  when  calling  through  vectors.  This  is  why 
placing  a  $00(X)  into  keyVector,  for  example,  causes  GEOS  ignore  the  vector. 
Other  examples  of  tiiis  usage  are  intTopVec,  intBotVec,  and  mouse  Vector. 

CallRoiitine  modifies  the  st  register  prior  to  performing  the  jsr.  It,  therefore, 
cannot  be  used  to  call  routines  that  expect  processor  status  flags  as  parameters 
(flags  may  be  returned  in  the  st  register,  however).  CallRoutine  may  be  called 
from  Interrupt  Level  (off  of  routines  in  IntTopVec  and  IntBotVec).  Do  not  use 
CallRoutine  to  call  inline  (i_)  routines,  as  it  will  not  return  properly. 


HandleCommand 


^******-'******<*  ****** 


DESCRIPTION:   Given  a  command  number  this  routine  handles  dispatching 
control  to  the  appropriate  routine. 

PASSED:  y        command  number 

RETURNS:  depends  on  command 

DESTROYED:       depends  on  command 

*************************************************************************** 


HandleCommand : 

cpy  #T0T_CMDS-1 
bgt  99$ 
Idx  CMDtabH,y 
Ida  CMDtabL,y 
jsr  CallRoutine 

99$: 

rts 


/  check  command  #  against  last  cmd  num 

;  exit  if  command  is  invalid 

;  get  high  byte  routine  address 

;  get  low  byte  of  routine  address 

;  call  the  routine 

s 

;  exit 


;  The  table  below  is  a  collection  of  the  the  high/low  bytes  of  the  routine 
;  associated  with  each  command  number.  If  a  command  is  not  yet  implemented. 


4 


CallRoutine 


;  use  the  UNIMPLEMENTED  constant  (SOOOO)  to  have  it  ignored, 
UNIMPLEMENTED  »  $0000  ;  CallRoutine  ignores  this 


CMDtabH: 

.byte 
.byte 
.byte 
.byte 
.byte 
.byte 


/high  bytes 

] UNIMPLEMENTED 

ICmdl 

]Cmd2 

]Cmd3 

)Cmd4 

ICmdS 


command  0 
command  1 
command  2 
command  3 
command  4 
command  5 


CMDtabL: 

.byte 
.byte 
.byte 
.byte 
.byte 
.byte 


;low  bytes 

[UNIMPLEMENTED 

(Cmdl 

[Cmd2 

(Cmd3 

[Cmd4 

(Cmd5 


command 
command 
command 
command 
command 
command 


TOT  CMOS 


(CMDtabL-CMDtabH)  /total  number  of  commands 


See  also: 


JsrToAux 
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CancelPrInt 


CancelPrint  (Apple) 


printer  driver 


Function: 

Parameters: 

Returns: 

Destroys: 

Description: 

Note: 
See  also: 


Cancel  printing  immediately,  clearing  any  buffers  on  the  printer  card  or  printer, 
none. 

X  STATUS  —  printer  error  code;  $00  =  no  error, 

assume  a,  y,  r0-r4. 

CancelPrint  instructs  the  printer  driver  to  cancel  the  current  printing  operation, 
clearing  any  data  already  accumulated  in  a  buffer  on  the  printer  or  the  printer  card. 
Its  main  use  is  to  allow  tihe  application  to  have  the  printer  really  stop  printing  if  the 
user  decides  to  cancel. 

The  CancelPrint  routine  does  not  work  properly  in  the  first  and  second  versions 
of  most  Apple  printer  drivers. 

StopPrint. 


I 

i 
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ChangeDiskDevice 


ChangePiskPevice  (C64,  cns) 


very  low-level  disk] 


Function: 

Parameters: 

Uses: 

Returns: 

Alters: 

Destroys: 
Description: 


Instruct  a  drive  to  change  its  serial  device  number. 

a  hffiWDEVNUM  —  new  device  number  to  give  current  drive  (byte). 

curDrive  drive  whose  device  number  will  change. 

X  error  ($00  =  no  error). 


curDrive 
curDevice 

a,  y. 


NEWDEVNUM. 
NEWDEVNUM. 


ChangeDiskDevice  requests  the  turbo  software  to  change  the  serial  device 
number  of  the  current  drive.  Most  applications  have  no  need  to  call  this  routine, 
as  it  is  in  the  realm  of  low-level  disk  utilities.  ChangeDiskDevice  is  used 
primarily  by  the  deskTop  and  Configure  programs  to  add,  rearrange,  and  remove 
drives. 


Be  aware  that  changing  the  device  number  merely  instructs  the  turbo  software  in 
the  drive  to  monitor  a  different  serial  bus  address.  Many  internal  GEOS  variables 
and  disk  drivers  expect  the  original  device  number  to  remain  unchanged 

Note:  If  ChangeDiskDevice  is  used  on  a  RAMdisk,  curDrive  and  curDevice  both 

change.  However,  because  of  the  natiure  of  the  RAMdisk  driver,  the  RAMdisk 
does  not  respond  as  this  new  device. 


Apple:  Apple  GEOS  has  no  ChangeDiskDevice  equivalent. 

See  also:  SetDevice. 
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ChkDkGEOS 


ChkDkGEOS  (C64,  ci28) 


mid-level  disk! 


Function: 
Parameters: 

Returns: 
Alters: 

Destroys: 
Description: 


Check  Commodore  disk  for  GEOS  format 


Apple: 
Example: 


r5 

nothing 

isGEOS 

st 


DIRHEAD  —  address  of  directory  header,  should  always  point  to 
curDirHead  (word). 


set  to  TRUE  if  disk  is  a  GEOS  disk,  otherwise  set  to 
FALSE. 

set  according  to  valu  in  isGEOS. 


ChkDkGEOS  checks  the  directory  header  for  the  version  string  that  flags  it  as  a 
GEOS  disk  (at  OFF^GEOS^ID).  The  primary  difference  between  a  GEOS  disk 
and  a  standard  Commodore  disk  is  the  addition  of  the  off-page  directory  and  the 
possiblity  of  GEOS  files  on  the  disk.  GEOS  files  have  an  additional  file  header 
block  that  holds  the  icon  image  and  other  information,  such  as  the  author  name 
and  permanent  name  string.  To  convert  a  non-GEOS  disk  into  a  GEOS  disk,  use 
SetGEOSDisk. 

OpenDisk  automatically  calls  ChkDkGEOS.  As  long  as  OpenDisk  is  used 
before  reading  a  new  disk,  applications  should  have  no  need  to  call 
ChkDkGEOS. 

All  ProDOS  disks  are  GEOS  compatible. 


.if   (064  I IC128) 

jsr  GetDirHead 
txa 

bne  99$ 

LoadW        r5, #curDirHead 

jsr  ChkDkGEOS 

beq  40$ 
;         code  here  to  handle  GEOS  disk 

bra  99$ 
50$: 

.         code  here  to  handle  non-GEOS  disk 


read  in  the  directory  header 
check  status 
exit  on  error 
point  to  directory  header 
Check  for  GEOS  disk 
if  not  a  GEOS  disk,  branch 

;  jump  to  exit 


See  also: 


99$:  rts 

SetGEOSDisk. 


exit 
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ClearCard 


ClearCardjAppie) 


card  driver  I 


Function:       Instructs  the  interface  card  to  stop  transmitting  data  and  clear  its  internal  buffer  if 
it  has  such  a  feature. 


Parameters:  none. 

Returns:  x 

Destroys:  a,  y. 
Description 


Note: 
See  also: 


STATUS  —  card  error  code;  $00  =  no  error  (byte) 


ClearCard  instructs  the  interface  card  to  immediately  stop  sending  data  and  clear 
its  internal  buffer  if  it  has  such  a  feature.  ClearCard  is  designed  to  be  called  by 
CancelPrint  to  abort  any  buffered  print  data,  but,  because  this  feature  is  rarely 
supported  by  interface  cards,  most  printer  drivers  omit  this  call  to  save  space. 

ClearCard  must  be  called  after  an  OpenCard  and  before  a  CloseCard. 

CancelPrint. 
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ClearMouseMode 


CiearMouseMode  (Apple,  C64,  ci28) 


mouse/sprite 


Function: 
Parameters: 
Returns: 
Alters: 

Destroys: 
Description: 


Stop  monitoring  the  input  device. 


nothing. 

nothing. 

mouseOn 
mobenble 

a,  X,  y,  r3L 


set  to  $00,  totally  disabling  all  mouse  tracking 
sprite  M)  bit  cleared  by  DisablSprite. 


ClearMouseMode  instructs  GEOS  to  totally  disable  its  monitoring  of  the  input 
device.  It  clears  mouseOn  to  reset  mouse  tracking  to  its  cleared  state  and  calls 
DisablSprite.  Applications  will  normally  not  have  a  need  to  call  this  routine.  It 
is  the  functional  opposite  of  StartMouseMode. 


See  also: 


StartMouseMode,  MouseOff. 
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ClearRam 


ClearRam  (Apple,  C64,  cm) 


memoryl 


Function: 
Parameters: 

Returns: 

Destroys: 

Description: 

Note: 

Example: 


Clear  a  region  of  memory  to  $00. 


rl 
rO 

nothing. 


ADDR  — address  of  area  to  clear  (word). 

COUNT  —  number  of  bytes  to  clear  (0  -  64K)  (word). 


a,  y,  rO,  rl,  r2L  ' 

ClearRam  clears  COUNT  bytes  starting  at  ADDR  to  $00.  It  useful  for 
initializing  ramsect  variable  and  data  sections. 

Do  not  use  ClearRam  to  initalize  rO  through  r2L.  Also,  for  when  space  is  at  a 
premium,  it  actually  takes  fewer  bytes  to  call  i_FillRam  with  a  fill  value  of  $00. 


initialize  buffers  and  variables  to  zero 

LoadW  rO,#varStart  ;  clear  variable  space 

LoadW  rl, # (varEnd-varStart)  ; 

jsr  ClearRam  ; 

LoadW  rO, #heapStart  ;  clear  heap 

LoadW  rl, # (heapEnd-heapStart)  / 

jsr  ClearRam  ; 


See  also: 


FiliRam,  InitRam. 
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Clockint 


ClOCkInt  (Apple) 


clock  driver! 


Function: 

Parameters: 

Alters: 


Destroys: 
Description: 


Example: 


Qock  driver  Interrupt  Level  routine.  Called  by  GEOS  during  Interrupt  Level, 
none. 

(usually)  year 
month 
day 
hour 
minutes 
seconds 

assume  a,  x,  y,  r0-rl5. 

GEOS  calls  Ciockint  during  Interrupt  Level,  which  allows  a  clock  driver  to 
have  an  Interrrupt  Level  routine.This  facility  is  used  primarily  by  the  software 
clock,  which  expects  to  be  called  approximately  FRAME  RATE  times  per 
second.  Every  time  Clockint  gets  called,  the  software  clock  decrements  a 
counter  that  is  initialized  to  FRAME^RATE.  When  the  counter  reaches  zero, 
approximately  one  second  has  elapsed. 

Hardware  clock  drivers  usually  have  a  Clockint  routine  that  simply  performs  an 
rts. 


.if   (APPLE)        ;  clock  drivers  only  exist  in  Apple  GEOS 
.★*★  Sample  Clockint  clock  driver  routine  *** 

************************************************************** 

;o  Clockint 


/Synopsis: 


This  is  called  at  interrupt  level  for  the  software  clock. 


/Author:  Andrew  Wilson  January  1988 

/Called  by:       Interrupt  Level  through  clock  driver  jump  table 

/Pass:  nothing 

/Returns:  nothing 

/Alters:  assume  a,  x,  y,  r0-rl5 

*  ***************************** 


o  ReadClockInt: 

Ida 

hour 

;  if  nothing  set,  exit 

ora 

minutes 

ora 

seconds 

ora 

year 

ora 

month 

ora 

day 

beq 

90$ 

dec 

counter  t 

•  have  a  second's  worth  of  int's  occurred 

bpl 

90$ 

•  branch  if  it  hasn't  happened 

/  this  code 

happens  once  a  second. 

assuming  interrupts  weren't  shut  off 

Idx 

#FRAME__RATE-1 

•  counter  <-  (interrupts/second)-! 

stx 

counter  '  < 

Idx 

#60-1 

?  X  <-  seconds/minute  (and  min/hr) 

•   (actually,  one  less  so  we  can  use  bge 

r    branch,  which  is  smaller) 

inc 

seconds  , 

r  add  one  second  to  clock 
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Clockint 


cpx 
bge 


seconds 
90$ 


;  do  we  add  another  minute? 
;  branch  if  seconds  don't  roll 


;  this  code  happens  roughly  once  a  minute,  assuming  interrupts  weren't  off 


Ida 
sta 
inc 
cpx 
bge 


#0 

seconds 
minutes 
minutes 
90$ 


;  reset  seconds 

;  save  the  new  seconds 

;  add  one  to  minutes 

;  do  we  add  another  hour? 

;  branch  if  minutes  don't  roll 


;  this  code  happens  once  an  hour,  assuming  interrupts  weren't  off 


sta 
inc 
Idx 
cpx 
bge 


minutes 

hour 

#24-1 

hour 

90$ 


;  reset  minutes 

/  add  another  hour  to  the  software  clock 

;  x  <-  (hours/day) -1 

;  do  we  add  another  day 

;  branch  if  hours  don't  roll 


;  this  code  happens  once  a  day,  assuming  interrupts  are  off 


50$: 


sta  hour 

inc  day 

Idy  month 

Ida  #28+1 

sta  febMonth 

Ida  year 

and  #%00000011 

bne  50$ 

inc  febMonth 

Ida  daysInMonth-l,y 

cmp  day 

bne  90$ 


zero  hours 
add  another  day 
get  the  current  month 
febMonth  <-  days  in  February+1 

check  for  leap  year 
(nice  and  convenient  that  4 

is  a  power  of  2) 
if  leap  year,  then  one  more  day  in  Feb. 

;  see  if  the  current  day  ends  the  month 
;  compare 

;  branch  if  month  doesn't  roll 


;  this  code  happens  once  a  month,  assuming  the  computer  lasts  that  long... 


Idx 
stx 
inc 
Ida 
cmp 
bit 


#1 

day 

month 

month 

#12 

90$ 


first  day  of  month 

save  it 

add  one  month 

see  if  we're  past  the  last  month 


;  this  code  happens  once  a  year.  It  rolls  over  in  1999,  and  so  we'll  need 
;  a  new  clock  driver  before  then... 


90$: 


Ida 
sta 
inc 

rts 


#1 

month 
year 


first  month  of  the  year 

new  year 

exit 


See  also: 


;  daysInMonth  is  the  number  of  days  in  each  month.  It  actually  co/itains 
;  number  of  days  plus  one  since  we  increment  days  before  we  check. 

daysInMonth:      .byte  32 

febMonth:  .byte  29  ;  February  is  modified  on  leap  years 

.byte  32,31,32,31,31,32,31,32,31,32 

.endif  ; (APPLE) 

ReadClock,  AuxDInt. 
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CioseCard 


CloseCard  (Apple) 


card  driver 


Function: 
Parameters:  none 
Returns:  x 
Destroys:       a,  y. 
Description 


Qose  access  to  interface  card 


STATUS  —  card  error  code;  $00  =  no  error  (byte) 


Example: 


CloseCard  closes  access  to  the  interface  card.  It  is  the  functional  opposite  of 
OpenCard.  The  printer  driver  sends  blocks  of  data  to  the  printer  between  calls  to 
OpenCard  and  CloseCard.  The  CloseCard  routine  in  most  card  drivers 
simply  returns  without  an  error,  but  printer  drivers  should  always  bracket  their 
access  to  die  card  driver  between  calls  to  OpenCard  and  CloseCard. 


.if  (APPLE)  ;  card  drivers 
;  Initialize  the  card 


only  exist  on  Apple  GEOS 


Dsr 
txa 
bne 


InitCard  ; 
90$ 

;  Open  the  card  so  we  access  the  printer 
OpenCard 


call  card  driver  init  routine 
check  status 
branch  if  error 


jsr 

txa  ; 
bne  90$  ; 

;  Initialize  printer 

Idy  #PRINITCODE  ; 

jsr  OutputByte  ; 

txa  ; 

bne  90$  / 

;  Close  the  card  and  exit 

jsr  CloseCard  ; 

90$: 

rts 

.endif  ; (APPLE) 


call  card  driver  open  routine 
check  status 
branch  if  error 


y  <-  control  code  to  init  printer 
send  through  card  to  printer 
check  status 
branch  if  error 


call  card  driver  close  routine 
exit  with  error  in  x 


See  also:  OpenCard. 
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CloseRecordFile 


CloseRecordFile  (Apple,  C64,  cns) 


VLIR  disk 


Function:       Close  the  current  VLIR  file  (updating  it  in  the  process)  so  that  another  may  be 
opened 


Parameters:  none. 
Uses: 


Returns: 
Alters: 


curDrive 
fileWrittent 

fileHeader 
fileSize 

dirEntryBuf 


if  FALSE,  no  updating  occurs  because  file  has  not  been 
written  to. 

VLIR  index  table  stored  in  this  buffer, 
total  number  of  disk  blocks  used  in  file  (includes  index 
block,  GEOS  file  header,  and  all  records), 
directory  entry  of  VLER  file. 


year,  month,  day,  hours,  minutes      for  date-stamping  file. 


Cpmrnodorg; 

curType 

curDirHead 

dir2Headt 

dir3Headt 

Apple: 
fileBytes 

curVBlknot 

VBMchangedt 

numVBMBlkst 


GEOS  64  V  1.3  and  later  for  detecting  REU  shadowing, 
this  buffer  must  contain  the  current  directory  header. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


total  number  of  bytes  in  file  (written  to  bytes  254, 255, 511, 
and  512  of  the  master  index  block), 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


set  to  FALSE  to  indicate  that  file  hasn*t  been  altered  since 
last  updated. 

used  for  temporary  storage  of  the  directory  block. 


Destroys: 
Description: 

C64  &  C128: 

Example: 
See  also: 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use 
X  error  ($00  =  no  error). 

fileWrittent 
diskBlkBuf 

^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
a,  y,  rl,  r4,  rS. 

CloseRecordFile  first  calls  UpdateRecordFile  then  closes  the  VLIR  file  so 
that  another  may  be  opened. 

Because  Commodore  GEOS  stores  the  BAM  in  global  memory,  the  application 
must  be  careful  not  to  corrupt  it  before  the  VLIR  file  is  updated  or  closed.  For 
more  information,  refer  to  UpdateRecordFile. 

See  example  at  AppendRecord. 

OpenRecordFile,  UpdateRecordFile. 
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CmpFString 


CmpFString  (Apple,  C64,  ci28) 


string! 


Function: 
Parameters: 


Returns: 

Destroys: 

Description: 


Note: 
Example: 


Compare  two  fixed-length  strings. 

X  SOURCE  —  zero-page  address  of  pointer  to  source  string  (byte  pointer 

to  a  word  pointer). 

y  DEST  —  zero-page  address  of  pointer  to  destination  string  (byte  pointer 

to  a  word  pointer). 

a  LEN  —  length  of  strings  (1-255).  A  LEN  value  of  $00  will  cause 

CmpFString  to  function  exacdy  like  CmpString,  expecting  a  null- 
terminated  source  string. 

s  t       status  register  flags  reflect  the  result  of  the  comparison. 

a,  X,  y 

CmpFString  compares  the  fixed-length  string  pointed  to  by  SOURCE  to  the 
string  of  the  same  length  pointed  to  by  DEST. 

CmpFString  with  a  LEN  value  of  $00  causes  the  routine  to  act  exactly  like 
CmpString. 

CmpFString  compares  each  character  in  the  strings  until  there  is  a  non-matching 
pair.  The  result  of  the  comparison  between  the  non-matching  pair  is  passed  back 
in  the  processor  status  register  (st).  If  the  strings  match,  the  z  flag  is  set.  This 
allows  the  application  to  test  the  result  of  a  string  comparison  with  standard  test 
and  branch  operations: 

bne  branch  if  strings  don't  match 

beq  branch  if  strings  match 

bcs  branch  if  source  string  is  greater  than  or  equal  to  dest  string 

bee  branch  if  source  string  is  less  than  dest  string 

The  strings  may  contain  internal  NULL'S.  These  will  not  terminate  the 
comparison. 


REG  SIZE 
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;size  of  each  record 


Find: 


LoadW 

r2,#NUM_RECS 

•  r2  <-  total  number  of  records 

LoadW 

rO,#Key 

•  rO  <-  pointer  to  keyword 

LoadW 

rl,#Data  , 

•  rl  <-  pointer  to  start  of  search  list 

10$: 

•  DO 

Idx 

#rO 

X  <-  source  string  «  key  , 

Idy 

#rl 

y  <-  dest  string  *  list 

Ida 

#REC_SIZE 

a  <-  length  of  each  record 

jsr 

CmpFString  < 

r      compare  key  with  current  record 

beq 

20$ 

if  they  match,  branch 

AddVW 

#REC  SIZE^rl 

otherwise  point  to  the  next  record 

DecW 

r2 

r2 —  (decrement  counter) 

bne 

10$ 

•  WHILE  (r2  >  0) 

;  code  to 

handle  no  matches  goes  here 

rts 
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CmpFStrIng 


.           code  to  handle  a  match  goes  here 

rts 

Key:    .byte  "alpha  " 
Data: 

.byte  "ZETA 

.byte  "0123456789ABcDeF"  ' 

.byte  "gAMma  over  beta  " 

.byte  "stewardesses  " 

.byte  "123ABC123abc 

.byte  "abcdefghi jklmnop" 

.byte  "qrstuvwxyz012345" 

•byte  "stewardess  " 

.byte  "beta  " 

.byte  "alpha 

.byte  "delta  " 

.byte  "steward  " 
EndData: 

NUM__RECS  «  (  (EndData-Data)  /REC_SIZE) 

.if      (   (Data  +  NUM_RECS*REC_SIZE)  *) 

.echo  Something  is  wrong  with  sort  data 


.endif 

See  also:       CmpString,  CopyFString. 
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CmpStrIng 


CmpString  (Apple,  C64,  cns)  string] 

Function:       Compares  two  null-terminated  strings. 

Parameters:    x  SOURCE  —  zero-page  address  of  pointer  to  source  string  (byte  pointer 

to  a  word  pointer). 

y  DEST  —  zero-page  address  of  pointer  to  destination  string  (byte  pointer 

to  a  word  pointer). 

Returns:        st      status  register  flags  reflect  the  result  of  the  comparison. 
Destroys:       a,  x,  y 

Description:  CmpString  compares  the  null-terminated  source  string  pointed  to  by  SOURCE 
to  the  destination  string  pointed  to  by  DEST.  The  strings  are  compared  a  byte  at  a 
time  until  either  a  mismatch  is  found  or  a  null  is  encountered  in  both  strings. 
CmpString  expects  the  strings  to  be  the  same  length;  strings  of  different  lengths 
are  treated  as  not  matching. 

CmpString  compares  each  character  in  the  strings  until  tiiere  is  a  non-matching 
pair.  The  result  of  the  comparison  between  the  non-matching  pair  is  passed  back 
in  the  processor  status  register  (st).  If  the  strings  match,  the  z  flag  is  set.  This 
allows  the  application  to  test  the  result  of  string  comparison  with  standard  test  and 
branch  operations: 


bne  branch  if  strings  don't  match 

beq  branch  if  strings  match 

bcs  branch  if  source  string  is  greater  than  or  equal  to  dest  string 

bee  branch  if  source  string  is  less  tiian  dest  string 


Note:  CmpString  cannot  compare  strings  longer  than  256  bytes  (including  the  null). 

The  compare  process  is  aborted  after  256  bytes. 

Example: 

Findi2: 


LoadW 

rO,#Original 

;  rO  <-  pointer  to  original  string 

LoadW 

rl, #Copy 

;  rl  <-  pointer  to  copy 

Idx 

#rO 

;  X  <-  source  string  =*  key 

Idy 

#rl 

;  y  <-  dest  string  «  list 

jsr 

CmpString 

;  compare  the  strings 

beq 

20$ 

/  if  they  match,  branch 

code  to 

handle  no  matches  goes  here 

rts 

code  to 

TZ3 

handle  a  match 

goes  here 

Origi 

.,/ce 

"Mark  Charles 

Heartless", NULL 

Copy: 

.byte 

"Mark  Charlie 

Heartless", NULL 

See  also:       CmpFString,  CopyString. 
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CopyFString  (Apple,  C64,  cns) 


string! 


Function: 
Parameters: 


Returns: 

Destroys: 

Description: 


Note: 
Example: 


Copy  a  fixed-length  string. 

X  SOURCE  —  zero-page  address  of  pointer  to  source  string  (byte  pointer 
to  a  word  pointer). 

y  DEST  —  zero-page  address  of  pointer  to  destination  buffer  (byte  pointer 
to  a  word  pointer). 

a  LEN  —  length  of  string  (1-255).  A  LEN  value  of  $00  will  cause 
CopyFString  to  function  exactiy  like  CopyString,  expecting  a  null- 
terminated  source  string. 

Buffer  pointed  to  by  DEST  contains  copy  of  source  string. 

a,  X,  y 

CopyFString  copies  a  fixed-length  string  pointed  to  by  SOURCE  to  the  buffer 
pointed  to  by  DEST.  If  Uie  source  and  destination  areas  overlap,  the  source  must 
be  lower  in  memory  for  the  copy  to  work  properly. 

Because  the  LEN  parameter  is  a  one-byte  value,  CopyFString  cannot  copy  a 
string  longer  tiian  255  bytes.  A  LEN  value  of  $00  causes  CopyFString  to  act 
exacdy  like  CopyString. 

The  source  string  may  contain  internal  NULL'S.  These  will  not  terminate  the 
copy  operation. 


LoadW 

LoadW 

Idx 

Idy 

Ida 

jsr 

SrcString: 

LENSTRING 

.ramsect 

DestString 

•psect 


r5, #SrcString 

rll,#DestString 

#r5 

#rll 

# LENSTRING 
CopyFString 


point  to  start  of  source  string 
point  to  start  of  destination  string 
X  <-  source  register  address 
y  <-  dest  register  address 
a  <-  length  of  string 
DestString  <-  SrcString  (copy) 


.byte  -This  is  a  string", CR, LF 
-  (*-SrcString) 

.blocJc  LENSTRING 


See  also:        CopyString,  CmpFString,  M oveData. 
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CopyFullScreen 


CopyFullScreen  (Apple) 


graphics! 


Function: 
Parameters: 


Destroys: 
Description: 

Note: 
Example: 


Copy  a  rectangle  of  the  full  width  of  the  screen  to  another  position  vertically. 
Operates  only  on  the  foreground  screen. 

rOL    SRCYl  —  top  line  of  source  region  (byte). 
rOH    SRCY2  —  bottom  line  of  source  region  (byte). 
r3L    DESTY  —  top  line  of  destination  (byte). 

where  (0, SRCYl)  defines  the  upper-left  corner  of  the  source  rectangle, 
(SCJPIXJVIDTH'1,SRCY2)  defines  the  lower-right  corner  of  the  source 
rectangle,  and  (Oj:>ESTY)  defines  the  upper-left  corner  of  the  destination. 

a,  X,  y,  rO,  r3L 

CopyFullScreen  is  optimized  to  quickly  copy  a  rectangular  area  of  the  full 
width  of  the  screen.  It  copies  the  desired  lines  from  the  source  to  the  destination 
(which  may  overlap  if  necessary).  The  copy  only  occurs  on  the  foreground 
screen. 

No  clipping  at  the  screen  top  or  bottom  is  performed;  the  values  passed  are 
assumed  to  lie  entirely  within  tiie  screen  boundaries. 


.if  (APPLE) 
SCROLL_TOP 
SCROLL__BOT 
SCROLL  INC 


»  SC_PIX_HEIGHT-1 
=  2 


top  line  of  scroll  region 
bottom  line  of  scroll  region 
lines  to  scroll 


ScrollUp: 

LoadB        rOL, #SCROLL_TOP+SCROLL_INC 
LoadB        rOH, #SCROLL_BOT 
LoadB        r3L, #SCROLL_TOP 
jmp  CopyFullScreen 

ScrollDown : 

LoadB        rOL,  #SCROLL__TOP 

LoadB        rOH, #SCROLL_BOT-SCROLL_INC 

LoadB        r3L, #SCROLL_TOP+SCROLL_INC 

jmp  CopyFullScreen 
.endif  ; (APPLE) 


rOL  <-  top  of  source 

rOH  <-  bottom  of  source 

r3L  <-  destination 

scroll,  let  CopyFullScreen  rts 


rOL  <-  top  of  source 

rOH  <-  bottom  of  source 

r3L  <-  destination 

scroll,  let  CopyFullScreen  rts 


See  also:        CopyLine,  CopyScreenBlock 
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CopyLine 


CopyLine  (Apple) 


graphics! 


Function: 
Parameters: 


Uses: 

Destroys: 
Description: 

Note: 


Example: 
See  also: 


Copy  a  horizontal  line  to  another  pixel  location;  operates  on  pixel  boundaries. 

r  1        SRCXl  —  x-co6rdinate  of  left  edge  of  source  line  (word). 
r2        SRCXl  —  x-coordinate  of  right  edge  of  source  line  (word). 
rOL       SRCY  —  y-coordinate  of  source  line  (byte). 
r4        DESTX  —  x-coordinate  of  left  edge  of  destination  (word). 
r3L      DESTY  —  y-coordinate  of  destination  (byte). 

where  (SRCXl, SRCY)  and  (SCRC2,SRCY)  define  the  endpoints  of  the  line  to 

move  to  (DESTX,DESTY). 

dispBufferOn: 

bit  7  —  copy  from  foreground  screen  if  set. 
bit  6  —  copy  from  background  buffer  if  set 
If  both  bits  are  set,  copy  occurs  on  both  screens. 

a,  X,  y 

CopyLine  copies  pixels  from  a  horizontal  source  line  to  a  destination  line.  The 
source  and  destination  coordinates  may  lie  on  any  pixel  boundary.  Pixels  will  be 
shifted  if  necessary.  The  source  and  destination  may  overlap. 

No  clipping  at  the  screen  edge  is  performed;  the  values  passed  are  assumed  to  lie 
entirely  within  the  screen  boundaries.  Also,  the  copying  is  appreciably  faster  if 
the  left-edge  x-coordinates  of  the  source  and  destination  lie  on  the  same  bit- 
boundary.  That  is,  if  (SRCXl  IP  )  ==  {DESTX  II 7). 


CopyFullScreen,  CopyScreenBlock 


J 
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CopyScreenBlock 


CopyScreenBlock  (Apple) 


graphics} 


Function: 
Parameters: 


Uses: 


Copy  a  rectangular  portion  of  the  screen  to  another  area. 

rl  SRCXl  —  x-coordinate  of  upper-left  of  source  (word), 

rOL  SRCYl  —  y-coordinate  of  upper-left  of  source  (byte) 

r2  SRCX2  —  x-coordinate  of  lower-right  of  source  line  (word). 

rOH  SRCY2  —  y-coordinate  of  lower-ri^t  of  source  (byte). 

r4  DESTX  —  x-coordinate  of  upper-left  of  destination  (word). 

r3L  DESTY  —  y-coordinate  of  upper-left  of  destination  (byte). 

where  (SRCXl, SRCYl)  defines  the  upper-left  corner  of  the  source  rectangle, 
(SCRCX2,SRCY2)  defines  the  lower-right  corner  of  the  source  rectangle  and 
(DESTXJDESTY)  defines  the  upper-left  corner  of  the  destination. 

dispBufferOn: 

bit  7  —  copy  from  foreground  screen  if  set. 
bit  6  —  copy  from  background  buffer  if  set 
If  both  bits  are  set,  copy  occurs  on  both  screens. 


Destroys:  a,  x,  y 
Description: 


Note: 


CopyScreenBlock  copies  pixels  from  a  source  rectangle  to  a  destination 
rectangle.  The  source  and  destination  coordinates  may  lie  on  any  pixel  boundary. 
Pixels  will  be  shifted  if  necessary.  The  source  and  destination  rectangles  may 
overlap. 

No  clipping  at  the  screen  edge  is  performed;  the  values  passed  are  assumed  to  lie 
entirely  within  the  screen  boundaries.  Also,  the  copying  is  appreciably  faster  if  ^ 
the  left-edge  x-coordinates  of  the  source  and  destination  lie  on  the  same  internal ' 
bit-boundary.  That  is,  if  (SRCX1%7)  ==  (DESTX%7). 


Example: 


.if  (APPLE) 

;***  Window  Coordinate  Constants  *** 


WIN__X 

WIN_WIDTH 

WIN~Y 

WIN^HEIGHT 

WIN_X2 

WIN_Y2 

SCROLL^INC 

ScrWinUp: 
Jsr 


LoadB 
LoadB 
LoadB 
jmp 

ScrWinDown : 
Jsr 


=  20 
«  85 
»  40 

-  110 

-  win_x+win_width 
»  win"y+win_hieght 

-  2 

;  scroll  window  up 
SetScrXPositions 


rOL, #WIN_Y+SCROLL_INC 
rOH,#WIN_Y2 
r3L, #WIN_Y 
CopyScreenBlock 

;  scroll  window  down 
SetScrXPositions 


pixel  x-position  (left  edge) 

pixel  width 

y-position 

height 

right  edge  x-position 
bottom  edge  y-position 

lines  to  scroll 


set  the  x-coordinates  for  scroll 
rl  <-  left  edge  source 
r2  <-  right  edge  source 
r4  <-  left  edge  dest   (==  rl) 

rOL  <-  top  of  source 

rOH  <-  bottom  of  source 

r3L  <-  top  edge  of  dest 

scroll,  let  CopyScreenBlock  rts 


set  the  x-coordinates  for  scroll 
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LoadB  rOL,  #WIN__Y 

LoadB  rOH, #WIN_Y2-SCR0LL_INC 

LoadB  r3L, #WIN_Y+SCROLL_INC 

jmp  CopyScreenBlock 


rl  <-  left  edge  source 

r2  <-  right  edge  source 

r4  <-  left  edge  dest  («»  rl) 

rOL  <-  top  of  source 

rOH  <-  bottom  of  source 

r3L  <-  top  edge  of  dest 

scroll,  let  CopyScreenBlock  rts 


SetScrXPositions :      ;  Set  the  common  dimensions  for  up  or  down  scroll 
—  Following  lines  changed  to  save  bytes   


LoadW 

rl,#WIN_ 

X 

rl  <-  left  edge  of  source 

LoadW 

r4,#WIN" 

[x 

r4  <-  left  edge  of  dest 

Ida 

#[WIN_x" 

get  low  byte  of  left  edge 

sta 

rlL 

and  store  it  in  low  byte  of 

sta 

r4L 

source  and  dest  left  edge 

Ida 

#)WIN_X 

do  the  same  with  the  hi  byte 

sta 

rlH 

sta 

r4H 

LoadW 

r2,  #WIN_ 

_X2 

•  r2  <-  right  edge  of  dest 

rts 

•  exit 

.endif  ; (APPLE) 
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Dabs  (Apple,  C64,  C128) 


mathl 


Function:       Compute  absolute  value  of  a  two's-complemcnt  signed  word 

Parameters:    x       OPERAND  —  zero-page  address  of  word  to  operate  on  (byte  pointer  to  a 

word  variable). 

Returns:        x,y  unchanged 

word  pointed  to  by  OPERAND  contains  the  absolute  value  result 


Destroys:  a 

Description:   Dabs  takes  a  signed  word  at  a  zero-page  address  and  retumes  its  absolute  value. 

The  address  of  the  word  (OPERAND)  is  passed  in  x.  The  absolute  value  of 
OPERAND  is  returned  in  OPERAND. 


Example: 
SeeAlso: 


The  equation  involved  is:  if  (value  <  0)  then  value  =  -value. 


DNegate. 
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DdeC  (Apple,  C64,  C128) 


mathl 


Function: 


Decrement  a  word 


Parameters:  x 


OPERAND  —  zero-page  address  of  word  to  decrement  (byte  pointer  to  a 
word  variable). 


Returns:        x,y  unchanged 

St       z  flag  is  set  if  resulting  word  is  $(XXX). 

zero  page  word  pointed  to  by  OPERAND  contains  the  decremented  word. 


Destroys:  a 


Description: 


Ddec  is  a  double-precision  routine  that  decrements  a  16-bit  zero-page  word 
Oow/high  order),  llie  absolute  address  of  the  word  is  passed  in  x.  If  the  result  of 
the  decrement  is  zero,  then  the  the  z  flag  in  the  status  register  is  set  and  can  be 
tested  with  a  subsequent  beq  or  bne.  Ddec  is  useful  for  loops  which  require  a 
two-byte  counter. 


Example: 


COUNT 
counter 
Ida 
sta 
Ida 
sta 
Idx 

10$: 

nop 
jsr 
bne 


-  $fffO 

-  aO 

# (COUNT 
counter 
# 1  COUNT 
counter+1 
♦counter 


Ddec 
10$ 


/counter  value 
•pseudoreg  to  count  with 
;init  pseudoregister 
;with  counter  value 


;tell  Ddec  which  zp  reg  to  use 

;do  nothing  in  loop 

/decrement  counter  (x  >  reg  addr.) 

;loop  until  done. 
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Ddiv  (Apple,  C64,  C128) 


math 


Function:       Unsigned  word-by-word  (double-precision)  division:  divides  one  unsigned  word 
by  another  to  produce  an  unsigned  word  result 


Parameters:  x 


Returns: 


OPERANDI  —  zero-page  address  of  word  dividend  (byte  pointer  to  a 
word  variable). 

y        0PERAND2  —  zero-page  address  of  word  divisor  (byte  pointer  to  a 
word  variable). 

Note:  result  =  OPERANDI  (word)  I  OPERAND2(word). 

X,  y,  and  word  pointed  to  by  OPERANDI  unchanged, 
word  pointed  to  by  OPERANDI  contains  the  result 
r8  contains  the  fractional  remainder  (word). 


Destroys:       a,  r9 

Description:  Ddiv  is  an  unsigned  word-by-word  division  routine  that  divides  the  word  at  one 
zero-page  address  (the  dividend)  by  the  word  at  another  (the  divisor)  to  produce  a 
16-bit  word  result  and  a  16-bit  word  fractional  remainder  The  word  in 
OPERANDI  is  divided  by  the  word  in  OPERANDI  and  the  result  is  stored  as  a 
word  back  in  OPERANDI.  The  remainder  is  returned  in  r8. 


Note:  Because  rS  and  r9  are  used  in  the  division  process,  they  cannot  be  used  to  hold 

operands. 

If  the  divisor  {OPERANDI)  is  greater  than  the  dividend  (OPERANDI),  then  the 
fractional  result  will  be  returned  as  $0000  and  OPERANDI  will  be  returned  in 
rS. 


Although  dividing  by  zero  is  an  undefined  mathematical  operation,  Ddiv  makes 
no  attempt  to  flag  this  as  an  error  condition  and  will  simply  return  incorrect 
results.  If  the  divisor  might  be  zero,  the  application  should  check  for  tiiis  situation 
before  dividing  as  in: 


Ida 

zpage,y 

;get  low  byte  of  divisor 

ora 

zpage-»-l,y 

/get  high  byte  of  divisor 

bne 

10$ 

;if  either  non-zero,  go  divide 

Jmp 

OivideByZero 

/else,  flag  error 

jmp 

Ddiv 

/divide  (Ddiv  will  rts) 

There  is  no  possibUity  of  overflow  (a  result  which  cannot  fit  in  16  bits). 

Example: 

SeeAIso:        DSdiv.  DMuIt.  BMult,  BBMult,  DivideBySeven. 
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DeleteDir 


DeleteDir  (Apple) 


high-level  disk 


Function:  Delete  a  subdirectory  from  the  current  directory  by  freeing  its  directory  blocks  and 
removing  its  directory  entry.  The  subdirectory  must  not  contain  any  files  to  be 
deleted 


Parameters:  rO 


DIRNAME  —  pointer  to  null-terminated  directory  name  (must  be  in 
main  memory.)  (word). 


Uses: 


curDrive 

curKBlkno 

curVBIknot 

VBMchangedt 

numVBMBIkst 


current  directory, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


Returns: 
Alters: 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
X         error  ($(X)  =  no  error). 


diskBlkBuf 
curVBIknot 
VBMchangedt 


used  for  temporary  block  storage, 
used  by  VBM  cacheing  routines. 

set  to  FALSE  by  VBM  cacheing  routines  to  indicate  cached 
VBM  block  has  already  been  flushed 


Destroys: 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
a,  y,  rl,  r4-r7,  r8H. 


Description:  Given  the  null-terminated  name  of  an  empty  subdirectory,  DeleteDir  will 
remove  the  subdirectory  from  the  disk  by  deleting  its  directory  entry  and  calling 
FreeDir  to  free  its  chain  of  directory  blocks. 

DeleteDir  first  calls  FindFile  to  get  the  directory  entry  of  the  subdirectory.  If 
the  subdirectory  does  not  exist  in  Ac  current  directory,  a  FILE^NOT^FOUND 
error  is  returned.  A  subdirectory  is  recognized  by  a  PRO  DIR  in  the  CjEOS  type 
byte  in  the  directory  entry  (at  OFF^FTYPE). 

DeleteDir  will  not  delete  a  subdirectory  that  has  files  in  it.  A 
DIR_NOT  EMPTY  error  will  be  returned.  (The  number  of  files  in  tiie 
subdirectoryls  stored  in  the  OFFB_FLCNT  word  of  the  directory's  header. 
This  maintains  this  value  by  calling  UpdateParent  when  files  are  added  or 
removed) 

C64  &  C128:  Commodore  GEOS  does  not  support  a  hierarchical  file  system. 


Example: 
See  also: 


DeleteDir,  DeleteFile,  FreeFile,  FreeBIock. 
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DeleteFile 


DeleteFile  (Apple,  C64,  ci28) 


high-level  disk| 


Function: 

Parameters: 

Uses: 


Returns: 
Alters: 


Destroys: 


Description: 


Delete  a  GEOS  file  by  deleting  the  its  directory  entry  and  freeing  all  its  blocks. 
Works  on  both  sequential  and  VLIR  files. 

rO        FILENAME  —  pointer  to  null-terminated  name  of  file  to  delete  (Apple 
GEOS:  must  be  in  main  memory,)  (word). 

curDrive 

Cpmmpijorg; 
curType 

Apple: 

curVBlknot 
VBMchangedt 
numVBMBlkst 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing. 


used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
X  error  ($00  =  no  error). 


diskBlkBuf 
dirEntryBuf 

Commodore: 

curDirHead 

dir2Headt 

dirSHeadt 

flleHeader 

Apple; 

curVBlknot 
VBMchangedt 


used  for  temporary  block  storage, 
deleted  directory  entry. 


BAM  updated  to  reflect  newly  freed  blocks. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 

temporary  storage  of  index  table  when  deleting  a  VLIR  file. 


used  by  VBM  cacheing  routines. 

set  to  FALSE  by  VBM  cacheing  routines  to  indicate  cached 
VBM  block  has  already  been  flushed 


^used  internally  by  GEOS  disk  routines:  applications  generally  don't  use. 

Commodore: 
a,  y,  r0-r9. 

Apple: 

a,  y,  rl,  r2L,  r4-r7,  rSH,  r9. 

Given  a  null-terminated  filename,  DeleteFile  will  remove  it  from  the  current 
directory  by  deleting  its  directory  entry  and  calling  FreeFile  to  free  all  the  blocks 
in  the  file. 

DeleteFile  first  calls  FindFile  to  get  the  directory  entry  and  ensure  the  file  does 
in  fact  exist.  If  the  file  specified  with  FILENAME  is  not  found,  a 
FILE  NOT  FOUND  error  is  returned. 
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C64  &  C128:  Since  Commodore  GEOS  does  not  support  a  hierarchical  file  system,  the  "current 
directory"  is  actually  the  entire  disk.  The  directory  entry  is  deleted  by  setting  its 
OFF^CFILE^TYPE  byte  to  $00. 

Apple:  Will  only  delete  a  file  from  the  current  directory.  To  delete  a  file  from  another 

directory,  the  application  must  change  directories  (refer  to  GoDirectory  for 
moving  to  another  directory). 

The  directory  entry  is  deleted  by  setting  its  OFF^FSTORE  byte  to  $00.  If  this 
directory  entry  is  the  last  in  a  particular  directory  block,  the  block  is  removed  and 
the  previous  directory  block's  next-block  pointer  (at  OFFB_NXTBLK)  is 
given  the  deleted  directory's  next-block  pointer,  thereby  maintaining  the 
continuity  of  the  directory  block  chain. 

After  deleting  the  directory  entry,  DeleteFile  calls  UpdateParent  to  update  the 
status  bytes  of  the  parent  directory. 

DeleteFile  cannot  delete  a  subdirectory.  To  delete  a  subdirectory,  use 
DeleteDir. 


Example: 
See  also: 


DeleteDir,  FreeDir,  FreeFile,  FreeBIock. 


DeleteRecord 


DeleteRecord  (Apple,  C64,  ci28) 


VLIR  disk! 


Function: 

Parameters: 
Uses: 


Returns: 
Alters: 


Destroys: 


Removes  the  current  VLIR  record  from  the  record  list,  moving  all  subsequent 
records  upward  to  fiU  the  slot  and  freeing  all  the  data  blocks  associated  with  the 
record. 


none. 

curDrive 
fileWrittent 

curRecord 
fileHeader 

Commodore: 

curType 

curDirHead 

dir2Headt 

dir3Headt 

Apple; 

curVBlknot 

VBMchangedt 

numVBMBlkst 


if  FALSE,  assumes  record  just  opened  (or  updated)  and 

reads  B AWVBM  into  memory. 

current  record  pointer 

VLIR  index  table  stored  in  this  buffer. 


GEOS  64  V  1.3  and  later:  for  detecting  REU  shadowing, 
current  directory  header/B  AM. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use 
X  error  ($00  =  no  error). 

« 

curRecord 
fileWrittent 


fileHeader 
fileSize 

Commodore! 
curDirHead 
dir2Headt 
dir3Headt 

Apple: 
fileBytest 


only  changed  if  deleting  the  last  record  in  the  table,  in  which 
case  it  becomes  the  new  last  record, 
set  to  TRUE  to  indicate  the  file  has  been  altered  since  last 
updated. 

new  record  added  to  index  table. 

decremented  to  reflect  any  deleted  record  blocks. 


current  directory  header/BAM  modified  to  finee  blocks. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


decremented  to  reflea  any  deleted  record  data. 
^used  internally  by  GEOS  disk  routines:  applications  generally  don't  use. 
Applg; 

a,  y,  rl-r2,  r4,  r6,  r7,  r8H. 

Commodore: 
a,  y,  r0-r9. 
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DeleteRecord 


Description:  DeleteRecord  removes  the  current  record  from  the  record  list  by  moving  all 
subsequent  records  upward  to  fill  the  current  record's  slot.  Any  data  blocks 
associated  with  the  record  are  freed 

DeleteRecord  does  not  update  the  B AMATBM  and  VLIR  file  information  on  the 
disk.  Call  CIoseRecordFile  or  UpdateRecordFile  to  update  the  file  when 
done  modifying. 

Example: 

See  also:        AppendRecord,  InsertRecord. 
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DIsablSprite 


DisablSprite  (Apple,  C64,  ci28) 


spritel 


Function:       Disable  a  sprite  so  that  it  is  no  longer  visible. 
Parameters:    r3L    SPRITE  —  sprite  number  (byte). 
Returns:  nothing. 
Alters:  mobenble 
Destroys:       a,  x 

Description:  DisablSprite  disables  a  sprite  so  that  it  is  no  longer  visible.  Although  there  are 
eight  sprites  available,  an  application  should  only  directly  disable  sprite  #2 
through  sprite  #7  with  DisablSprite.  Sprite  #0  (the  mouse  pointer)  is  always 
enabled  when  GEOS  mouse-tracking  is  enabled  (disable  mouse-tracking  with 
mouseOff)*  and  sprite  #1  (the  text  cursor)  should  be  disabled  with  PromptOff. 


Example: 


See  also: 


EnablSprite,  MouseOff,  PromptOff,  DrawSprite,  GetSpriteData, 
PosSprite,  InitSprite. 


DivideBySeven 


DivideBySeven  (Apple) 


graphics 


Function: 

Parameters: 

Returns: 

Destroys: 
Description: 

Note: 
Example: 


Quickly  divide  a  word  value  (between  0  and  649)  by  seven  for  direct  screen 
access  graphic  operations. 

a  ]DIVIDEND  —  high  byte  of  word  to  divide  by  seven  (byte), 
X        [DIVIDEND  —  low  byte  of  word  to  divide  by  seven  (byte). 

a       quotient  (byte), 
y       remainder  (byte). 
X  unchanged. 


DivideBySeven  is  a  highly  specialized  divide  routine  designed  for  applications 
that  require  direct  screen  access.  The  Apple's  double  high-res  screen  is  based  on  a 
seven-bit  byte  which  requires  dividing  the  x-posirion  by  seven  to  calculate  the 
byte-position.  The  quotient  is  the  byte  position  in  a  scanline  and  the  remainder  is 
the  bit-position  in  that  byte.  DivideBySeven  uses  a  series  of  lookup  tables  to 
quickly  calculate  the  quotient  and  the  remainder. 

Although  the  maximum  screen  x-position  on  the  Apple  is  559 
(SC^PIX^WIDTH  -  1),  DivideBySeven  will  handle  values  up  to  649  so 
that  graphics  can  be  generated  for  64()-column  printer  drivers. 

The  average  computational  time  for  DivideBySeven  is  roughly  21  cycles. 


XorPoint  —  invert  a  single  screen  point  on  Apple. 

« 

Pass:  r3  x-coordinate 


rllL  y-coordinate 


Uses: 


dispBuf ferOn 


Destroys: 


a,  X,        rS,  r6. 


XorPoint: 


jsr 
Idx 
jsr 
Ida 
Idx 
jsr 
pha 
tya 
tax 
Pla 
jsr 
Ida 


SetCorrectPage 
GrBit Table, X 


TempHideMouse 
rllL 

GetScanLine 


DivideBySeven 


r3H 
r3L 


/turn  off  sprites  temporarily 
;get  y-coordinate 

;set  r5  and  r6  with  scanline  addressses 
;get  hi  of  x-coordinate 
;get  lo  of  x-coordinate 
/calculate  byte  and  bit  offsets 
/save  byte  offset 

/transfer  bit  offset  to  x-register 
/to  pass  to  SetCorrectPage 
/and  put  byte  offset  into  a-reg 
/ (see  GetScanLine  reference) 
/get  pixel  bit-mask 
/xor  pixel  in  first  buffer 
/store  into  both  buffers 
/if  necessary 


eor 
St  a 
sta 
rts 


(r6),y 
(r5),y 
(r6),y 


GrBit Table: 


.byte  %00000001,%00000010,%00000100,%00001000 
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CONriDENTIAL 


DivideBySeven 


.byte  %00010000,%00100000,%01000000,%10000000 

See  also:        GetScanLine,  NormalizeX,  DdiV. 
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DMult  (Apple,  C64,  C128) 


math 


Function: 
Parameters: 

Returns: 

Destroys: 
Description: 

Note: 

Example: 
SeeAlso: 


Unsigned  word-by-word  (double-precision)  multiply:  multiplies  two  unsigned 
words  to  produce  an  unsigned  word  result 

X       OPERANDI  —  zero-page  address  of  word  multiplicand  (byte  pointer  to  a 
word  variable). 

y       0PERAND2  —  zero-page  address  of  word  multiplier  (byte  pointer  to  a 
word  variable). 

Note:  result^  OPERANDI  (word)  *  OPERAND2(word). 

X,  y,  word  pointed  to  by  OPERANDI  unchanged, 
word  pointed  to  by  OPERANDI  contains  the  word  result. 

a, r6-r8. 

DMult  is  an  unsigned  word-by-word  multiplication  routine  that  multiplies  the 
word  at  one  zero-page  address  by  the  word  at  another  to  produce  a  16-bit  word 
result  (all  stored  in  low/high  order).  The  word  in  OPERANDI  is  multipliod  by  the 
word  in  OPERANDI  and  die  result  is  stored  as  a  word  back  in  OPERANDI. 

Because  r6,  r7  and  r8  are  destroyed  in  the  multiplication  process,  they  cannot  be 
used  to  hold  the  operands. 

Overflow  in  the  result  (beyond  16-bits)  is  ignored. 


BMult,  BBMult,  Ddiv,  DSdiv. 


This  page  Intentionally  left  blank  to  maintain  right /left  (verso/recto) 
page  ordering.  Final  version  will  correct  this. 


□negate 


Dnegate   (Apple,  C64,  C128)  math 


Function:       Negate  a  signed  word  (two's  complement  sign-switch). 

Parameters:    x        OPERAND  —  zero-page  address  of  word  to  operate  on  (byte  pointer  to  a 

word  variable). 

Returns:        x,y  unchanged 

word  pointed  to  by  OPERAND  contains  the  negated  word. 

Destroys:  a 

Description:  DNegate  negates  a  zero-page  word.  The  absolute  address  of  the  word 
(OPERAND)  is  passed  in  x.  The  absolute  value  of  OPERAND  is  returned  in 
OPERAND. 

The  operation  of  this  routine  is:  value  =  (value  ^  $ffff)  +  1. 

Example: 

SeeAlso:  Dabs. 
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DoBOp 


DoBOp  (C128) 


memory! 


Function :       Back-RAM  memory  move/swap/verify  primitive. 

Parameters:    rO  ADDRl  —  address  of  first  block  in  application  memory  (word). 

r  1  ADDR2  —  address  of  second  block  in  application  memory  (word), 

r 2  COUNT — number  of  bytes  to  operate  on  (word). 

r3L  AlBANK— ADDRl  bank:  0  =  front  RAM;  1  =  back  RAM  (byte). 

r3H  A2B ANK — ADDR2  bank:  0  =  front  RAM;  1  =  back  RAM  (byte), 

y  MODE  —  operation  mode: 


0 

0 

move  from  memory  at  ADDRl  to  memory  at  ADDR2. 

0 

1 

move  from  memory  axADDRl  to  memory  n  ADDRl. 

1 

0 

swap  memory  at  ADDRl  with  memory  at  ADDRl. 

1 

1 

verify  (compare)  memory  at  ADDRl  against  memory  at  ADDR2. 

Note:  the  DoBOp  MODE  parameter  closely  matches  the  low  nyblle  of  the  DoRAMOp 
CMD  parameter. 

Returns:        r0-r3  unchanged. 

When  verifying: 

X       $00  if  data  matches;  $ff  if  mismatch. 
Destroys:       a,  x,  y 

Description:  DoBOp  is  a  generalized  memory  primitive  for  dealing  with  both  memory  banks 
on  the  Commodore  128.  It  is  used  by  MoveBData,  SwapBData,  and 
VerifyBData. 

Note:  DoBOp  should  only  be  used  on  designated  application  areas  of  memory.  When 

moving  memory  within  the  same  bank,  the  destination  address  must  be  less  than 
source  address.  When  swapping  memory  within  the  same  bank.  ADDRl  must  be 
less  than  i4/?D/?2. 


Example: 
See  also: 


MoveBData,  SwapBData,  VerifyBData,  DoRAMOp. 
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DoDlgBox 


DoDlgBoX   (Apple,  C64,  C128)  dialog  box| 

Initializes,  displays,  and  begins  interaction  with  a  dialog  box. 

rO        DIALOG  —  pointer  to  dialog  box  definition  (word). 
rS-rlO  can  be  used  to  send  parameters  to  a  dialog  box. 

rOL      return  code:  typically  the  number  of  the  system  icon  clicked  on  to  exit 
Note:  returns  when  dialog  box  exits  through  RstrFrmDialog. 

Destroys:  n/a 

Description:  DoDlgBox  saves  off  the  current  state  of  the  system,  places  GEOS  in  a  near- 
warmstart  state,  displays  the  dialog  box  according  to  the  definition  table  (whose 
address  is  passed  in  rO),  and  begins  tracking  the  user's  interaction  with  the  dialog 
box.  When  the  dialog  box  finishes,  the  original  system  state  is  restored,  and 
control  is  returned  to  the  application. 

Simple  dialog  boxes  will  typically  contain  a  few  lines  of  text  and  one  or  two 
system  icons  (such  as  OK  and  CANCEL).  When  the  user  clicks  on  one  of  these 
icons,  the  GEOS  system  icon  routine  exits  the  dialog  box  with  an  internal  call  to 
RstrFrmDialog,  passing  the  number  of  the  system  icon  selected  in 
sysDBData.  RstrFrmDialog  restores  the  system  state  and  copies 
sysDBData  to  rOL. 


Function: 
Parameters: 

Returns: 


More  complex  dialog  boxes  will  have  application-defined  icons  and  routines  that 

get  called.  These  routines,  themselves,  can  choose  to  load  a  value  into 

sysDBData  and  call  RstrFrmDialog. 

« 

Dialog  boxes  cannot  be  nested.  That  is,  a  dialog  box  should  never  call 
DoDlgBox. 

Apple:  DoDlgBox  automatically  calls  InitForDialog  as  part  of  its  initialization 

sequence. 

Note:  Part  of  the  system  context  save  within  DoDlgBox  saves  the  current  stack 

pointer.  Dialog  boxes  cannot  be  nested.  DoDlgBox  is  not  reentrant.  That  is,  a 
dialog  box  should  never  call  DoDlgBox. 

Example: 

See  also:        RstrFrmDlg,  InitForDialog,  RestoreSysRam,  SaveFG. 
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Dolcons 


DoICOnS  (Apple,  C64,  C128) 


icon/men 


Function:       Display  and  activate  an  icon  table. 

Parameters:    rO      ICONTABLE  —  pointer  to  the  icon  table  to  use. 

Uses:  dispBufferOn: 

bit  7  —  draw  icons  to  foreground  screen  if  set. 
bit  6  —  draw  icons  to  background  screen  if  set. 

Destroys:       r0-rl5,  a,  x,  y 


Description: 


Dolcons  takes  an  icon,  draws  the  enabled  icons  (those  whose 
OFF_PIC_ICON  word  is  non-zero)  and  instructs  MainLoop  to  begin  tracking 
the  user's  interaction  with  the  icons.  This  routine  is  the  only  way  to  install  icons. 
Every  application  should  install  at  least  one  icon,  even  if  only  a  dummy  icon. 

If  Dolcons  is  called  while  another  icon  table  is  active,  the  new  icons  will  take 
precedence.  The  old  icons  are  not  erased  from  the  screen  before  the  new  ones  are 
displayed. 


Dolcons  is  a  complex  routine  which  affects  a  lot  of  system  variables  and  tables. 
The  following  is  an  outline  of  its  major  actions: 

1:  All  enabled  icons  in  the  table  are  drawn  to  the  foreground  screen  and/or  the 
background  buffer  based  on  the  value  in  dispBufferOn. 

2:  StartMouseMode  is  called.  If  the  OFF  JC  XMOUSE  word  of  the  icon 
table  header  is  non-zero,  then  StartMouseMode  loads  mouseXPosition 
and  mouse Yposition  with  the  values  in  the  OFF  IC  XMOUSE  and  the 
OFF  IC^^YMOUSE  parameters  of  the  icon  "table  header  (see 
StartMouseMode  for  more  information). 

4:  faultData  is  cleared  to  $00,  indicating  no  faults. 

5:  If  the  MOUSEON^BIT  of  mouseOn  is  clear,  then  die  MENUON  BIT 
is  forced  to  one.  Thii  is  because  GEOS  assumes  that  it  is  in  a  power-up"state 
and  that  nniouse  tracking  should  be  fully  enabled.  If  the  MOUSEON  BIT  bit 
is  set,  GEOS  leaves  the  menu-scan  alone,  assuming  that  the  currenFstate  of 
the  MENUON^BIT  is  valid 

6:  The  ICONSON^BIT  and  MOUSEON  BIT  bits  of  mouseOn  are  set, 
thereby  enabling  icon-scanning.  " 

When  an  icon  event  handler  is  given  control,  rOL  contains  the  number  of  the  icon 
clicked  on  (beginning  with  zero)  and  rOH  contains  TRUE  if  the  event  is  a 
double-click  or  FALSE  if  the  event  is  a  single  click. 

Example: 

See  Also:  DoMenu. 
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DoinlineReturn 


DoInlineReturn  (Apple,  C64,  cus) 


utility 


Function: 
Parameters: 

Returns: 

Uses: 

Destroys: 

Description: 


Note: 


Return  from  an  inline  subroutine. 


a 


DATABYTES  —  number  of  inline  data  bytes  following  the  jsr  plus 
one(byte). 

staj:k  top  byte  on  stack  is  the  status  register  to  return  (execute  a  php  just  before 
calling). 

(to  the  inline  jsr)  x,  y  unchanged  from  the  jmp  DoInlineReturn.  st  register  is 
pulled  from  top  of  stack  with  a  pip. 

returnAddress     return  address  as  popped  off  of  stack. 

a 

DoInlineReturn  simulates  an  rts  from  an  inline  subroutine  call,  properly 
skipping  over  the  inline  data.  Inline  subroutines  (such  as  the  GEOS  routines 
which  begin  with  i  )  expect  parameter  data  to  follow  the  subroutine  call  in 
memory.  For  example,  the  GEOS  routine  i_Rectangle  is  called  in  the  following 
fashion: 


Jsr 
.byte 
.word 
Jsr 


XI,  X2 


i_Rect angle 


; subroutine  call 
/Inline  data 


FrameRectangle 


; returns  to  here 


Now  if  i_Rectangle  were  to  execute  a  normal  rts,  the  program  counter  would 
be  loaded  with  the  address  of  the  inline  data  following  the  subroutine  call. 
Obviously,  inline  subroutines  need  some  means  to  resume  processing  at  the 
address  following  the  data.  DoInlineReturn  Provides  this  facility.  The  normal 
return  address  is  placed  in  the  global  variable  returnAddress.  This  is  the  return 
address  as  it  is  popped  off  the  stack,  which  means  it  points  to  the  third  byte  of  the 
inline  jsr  (an  rts  increments  the  address  before  resuming  control).  TTie  status 
registers  is  pushed  onto  the  stack  with  a  php,  DoInlineReturn  is  called  with 
the  number  of  inline  data  bytes  plus  one  in  the  accumulator,  and  control  is 
returned  at  the  instruction  following  the  inline  data. 

Inline  subroutines  operate  in  a  consistent  fashion.  The  first  thing  one  does  is  pop 
the  return  address  off  of  the  stack  and  store  it  in  returnAddress.  It  can  then 
index  off  of  returnAddress  as  in  Ida  (return Address),y  to  access  the  inline 
parameters,  where  the  y-register  contains  $01  to  access  the  first  parameter  byte, 
$02  to  access  die  second,  and  so  on  (not  $00,  $01,  $02,  as  might  be  expected 
because  the  address  actually  points  to  the  third  byte  of  the  inline  jsr).  When 
finished,  the  inline  subroutine  loads  the  accumulator  with  the  number  of  inline 
data  bytes  and  executes  a  jmp  DoInlineReturn. 

DoInlineReturn  must  be  called  with  a  jmp  (not  a  jsr)  or  an  unwanted  return 
address  will  remain  on  die  stack.  The  x  and  y  registers  are  not  modificnd  by 
DoInlineReturn  and  can  be  used  to  pass  parameters  back  to  the  caller.  Inline 
calls  cannot  be  nested  widiout  saving  the  contents  cf  returnAddress.  An  inline 
routine  will  not  work  correctly  if  not  called  directly  through  a  jsr  (e.g., 
CallRoutine  cannot  be  used  to  call  an  inline  subroutine). 
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DolnlineReturn 


Example: 


; Invert icalLine 

;         Inline  version  of  VertlcalLlne. 
;Pass : 

;  .word  xl 
;  . word  x2 
;         .byte  yl 

l^VertlcalLine: 

V_BYTES  -  5  /number  of  Inline  bytes  In  call 

;Save  away  the  inline  return  address 
PopW  returnAddress 

;Load  up  VertlcalLlne * s  parameters 


Idy 
Ida 
sta 


#V_BYTES 

(returnAddress) ,y 
rllL 


;get  yl  parameter  first 


10$: 


dey 
Ida 
sta 
cpy 
bne 


(returnAddress) ,  y 

r3L-l,y 

#1 

10$ 


/load  other  params  in  a  loop 
/They  occupy  consecutive  GEOS 
/pseudoregisters,  so  this  will. 
/wor)c  correctly 


/Now 


call  VertlcalLlne  with  registers  loaded 
jsr  VertlcalLlne 


/and 


do  an  inline  return  when  we  come  back 
php 

Ida  #V_BYTES+1 
jmp  DolnlineReturn  / 


•save  St  reg  to  return 
/#  of  bytes  i 

/jump  to  inline  return.  Do  not  jsr! 
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DoMenu 


DoMenu  (Apple,  C64,  cm) 


icon/menu 


Function: 
Parameters: 

Destroys: 
Description: 


Displays  and  activates  a  menu  structure. 

rO      MENU  —  pointer  to  the  menu  structure  to  display, 
a       POINTER_OVER  —  which  menu  item  (numbered  starting  with  zero)  to 
center  the  pointer  over. 

r0-rl3,  a,  x,  y 

DoMenu  draws  the  main  menu  (the  first  menu  in  the  menu  structure)  and 
instructs  MainLoop  to  begin  tracking  the  user's  interaction  with  the  menu.  This 
routine  is  the  only  way  to  install  a  menu. 

If  DoMenu  is  called  while  another  menu  structure  is  active,  the  new  menu  will 
take  precedence.  The  old  menu  is  not  erased  from  the  screen  before  the  new  menu 
is  displayed.  If  the  new  menu  is  smaller  (or  at  a  different  position)  than  the  old 
menu,  parts  of  the  old  menu  may  be  left  on  the  screen.  A  typical  way  to  avoid  this 
is  to  erase  the  old  menu  with  a  call  to  Rectangle,  passing  the  positions  of  the 
main  menu  rectangle  and  drawing  in  a  white  pattern.  However,  a  more  elegant 
solution  involves  calling  Recover AlIMenus,  which  will  erase  any  extant  menus 
by  recovering  from  the  background  buffer. 

DoMenu  is  a  complex  routine  which  affects  a  lot  of  system  variables  and  tables. 
The  following  is  an  outline  of  its  major  actions: 

1:  Menu  level  0  (main  menu)  is  drawn  to  the  foreground  screen. 

2:  StartMouseMode  is  called.  mouseXPosition  and  mouseYpositlon  are 
set  so  that  the  pointer  is  centered  over  the  selection  number  passed  in  a. 
Under  Apple  GEOS,  if  the  the  POINTER.OVER  number  in  tiie  accumulator 
has  its  high-bit  set,  then  the  mouse  will  not  be  repositioned  Under  GEOS  64 
and  GEOS  128,  DoMenu  always  forces  the  mouse  to  a  new  position.  If  you 
do  not  want  the  mouse  moved,  surround  the  call  to  DoMenu  with  code  to 
save  and  restore  the  mouse  positions.  The  following  code  fragment  will  install 
n>enus  widiout  moving  the  mouse. 


DoMenu2 : 


.if  (APPLE) 

Ida  4$80 

jsr  DoMenu 
.else  ; (C64  i I  C128) 
php 
sei 

PushH  mouseXPos 

PushB  mouseYPos 

Ida  «0 

jsr  DoMenu 

PopB  mouseYPos 

PopW  mouseXPos 

pip 

.endif 

rts 


;set  high-bit  so  mouse  is  not  repositioned 
;put  up  the  menu 


; disable  interrupts  around  call 


;save  mouse  x 

;save  mouse  y 

; dummy  menu  value 

/install  menus  (mouse  will  move) 

/restore  original  mouse  y 

/restore  original  mouse  x 

/restore  interrupts 
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DoMenu 


3:  SIowMouse  is  called.  With  a  joystick  this  will  kill  all  accumulated  speed  in 
the  pointer,  requiring  the  user  to  reacceleratc.  With  a  proportional  mouse,  this 
will  have  no  effect 

4:  fauItData  is  cleared  to  $00,  indicating  no  faults. 

5:  If  the  MOUSEON^BIT  of  mouseOn  is  clear,  then  the  ICONSON^BIT 
is  forced  to  one.  Thii  is  because  GEOS  assumes  that  it  is  in  a  power-upTstate 
and  that  mouse  tracking  should  be  fully  enabled.  If  the  MOUSEON  BIT  bit 
is  set,  GEOS  leaves  the  icon-scan  alone,  assuming  that  the  ICONSON_BIT 
is  valid. 

6:  The  MENUON_,BIT  and  MOUSEON^BIT  bits  of  mouseOn  are  set, 
thereby  enabling  menu-scanning. 

7:  The  mouse  fault  variables  (mouseTop,  mouseBottom,  mouseLeft,  and 
mouseRight)  are  set  to  the  full  screen  dimensions. 

Example: 

See  Also:       Dolcons,  GotoFirstMenu,  DoPreviousMenu,  ReDoMenu. 
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DoneWithIO 


DoneWithIO  (C64,  ci28) 


very  low-level  disk| 


Function:       Restore  system  after  I/O  across  the  serial  bus. 
Parameters:  none. 
Returns:  nothing. 
Destroys:       a,  y. 

Description:  DoneWithIO  restores  the  state  of  the  system  after  a  call  to  InitForlO.  It 
restores  the  interrupt  status,  turns  sprite  DMA  back  on,  returns  the  128  to  its 
original  clock  speed,  and  switches  out  the  ROM  and  I/O  banks  if  appropriate 
(only  on  C64). 

Disk  and  printer  routines  access  the  serial  bus  between  calls  to  InitForlO  and 
DoneWithIO. 

Apple:  Apple  GEOS  has  no  DoneWithIO  equivalent 

Example:       See  WriteBIock. 
See  also:  InitForlO. 
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DoPreviousMenu 


DoPreviousMenu  (Apple,  C64,  cns) 


icon/menu 


Function:       Retracts  the  current  sub-menu  and  reactivates  menus  at  the  previous  level. 

Parameters:  none. 

Destroys:       assume  rO-rlS,  a,  x,  y 


Description: 


Note: 


Example: 
See  Also: 


DoPreviousMenu  is  used  by  a  menu  event  handler  to  instruct  GEOS  to  back  up 
one  level  of  menus,  erasing  the  current  menu  from  the  foreground  screen  and 
making  the  parent  menu  active  when  control  is  returned  to  MainLoop. 
menuNumber  is  decremented. 

When  using  DoPreviousMenu,  if  the  parent  menu  (the  one  which  will  be  given 
control)  is  of  type  UN_CONSTRAINED,  then  the  mouse  must  be  manually 
repositioned  over  the  parent  menu.  This  can  be  done  by  loading 
mouseXPosition  and  mouseYPosition  with  values  calculated  from  the  menu 
structure.  If  the  parent  menu  is  of  type  CONSTRAINED,  then  the  mouse  is 
automatically  positioned  over  the  selection  in  the  parent  menu  which  led  to  tiie 
sub-menu. 

DoPreviousMenu  may  be  called  repeatedly  to  back  up  more  than  one  level. 

Do  not  call  DoPreviousMenu  when  the  menu  is  at  level  0  (menuNumber  = 
$00).  The  effects  may  be  disasterous. 


DoMenu,  GotoFirstMenu,  ReDoMenu,  RecoverMenu. 
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DoRAMOp 


DoRAMOp   (C64  vL3  &  C128) 


memory  I 


Function: 
Parameters: 


Returns: 


Destroys: 


Primitive  for  communicating  with  REU  (RAM-Expansion  Unit)  devices. 

rO  ADDRl  —  address  in  Commodore  to  start  (word). 

rl  ADDR2  —  address  in  REU  bank  to  start  (word). 

r2  COUNT  —  number  of  bytes  to  operate  with  (transfer  length)  (word). 

r3L  REUB ANK  —  REU  bank  number  to  use  (byte). 

y  CMD  —  command  to  send  to  REU  (byte). 


r0-r3  unchanged. 
X        error  code: 


$00  (no  error)  or  DEV^NOT^FOUND  if  bank  or  REU 
not  available. 
REU  status  byte  and'ed  with  $60 


Description:  DoRAMOp  is  a  very  low-level  routine  for  communicating  with  a  RAM- 
expansion  unit  on  a  C64  or  C128.  This  routine  is  a  "use  at  your  own  risk"  GEOS 
primitive 


DoRAMOp  operates  with  the  with  the  RAM-expansion  unit  direcdy  and  handles 
all  the  necessary.communication  protocols  and  clock-speed  save/restore  (if 
necessary). 

The  CMD  parameter  is  stuffed  into  the  REC  Command  Register 
(EXP_BASE+$01).  Although  DoRAMOp  does  no  error  checking  on  this 
parameter,  it  expects  the  high-nybble  to  be  %1001  (transfer  with  current 
configuration  and  disable  FFOO  decoding).  The  lower  nybble  can  be  one  of  the 
following: 

%00    Transfer  from  Commodore  to  REU. 
%01    Transfer  from  REU  to  Commodore. 
%10  Swap. 
%11  Verify. 

Note:  the  low  nybble  of  the  DoRAMOp  CMD  parameter  closely  matches  the  DoBOp 
MODE  parameter. 

Note:  On  a  Commodore  128,  if  the  VIC  chip  is  mapped  to  front  RAM  (with  the  MMU 

VIC  bank  pointer),  the  REU  will  read/write  using  front  RAM.  Similarly,  if  the 
VIC  chip  is  mapped  to  back  RAM,  the  REU  will  read/write  using  back  RAM.  The 
REU  ignores  the  stadard  bank  selection  controls  on  die  8510.  GEOS  128  defaults 
with  die  VIC  mapped  to  front  RAM. 

For  more  information  on  the  Commodore  REU  devices,  refer  to  the  Commodore 
1764  RAM  Expansion  Module  User's  Guide  or  die  170011750  RAM  Expansion 
Module  User's  Guide. 


Example: 

See  also:       StashRAM,  FetchRAM,  SwapRAM,  DoBOp. 
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DownPirectory  (Apple) 


mid-level  disk 


Function: 
Parameters:  r9 
Uses: 
Returns: 


Makes  a  subdirectory  (child  directory)  in  the  current  directory  the  new  current 
directory. 

DIRENTRY  —  pointer  to  directory  entry  of  subdirectory,  usually  points 
to  dirEntryBuf  (must  be  in  main  memory)  (word). 


curDrive 
curKBlkno 


current  directory. 


X         error  ($00  =  no  error), 
y         pathname  status  ($00  =  OK;  BFR^OVERFLOW  =  pathname  longer 
than  pathnameBuO- 

Alters:  curKBlkno         new  current  directory. 

curDirHead        header  of  new  directory. 

pathnameBuf^      system  pathname  buffer  updated  to  reflect  new  path. 

curDirTabLot 

curDirTabHit 

^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
Destroys:       a,  rl,  r4. 

Description:   DownDirectory  moves  down  one  level  in  the  hierarchical  file  system,  making  a 
specific  child  directory  the  current  working  directOTy. 

The  directory  entry  of  the  subdirectory  is  a  standard  data  structure  returned  by 
routines  such  as  FindFlle,  GetlstDirEntVy  and  GetNextDirEntry.  A 
subdirectory  has  a  PRO^DIR  (ProDOS  directory)  GEOS  file  type. 

€64  &  C128:  Comnxxlore  GEOS  does  not  support  a  hierarchical  file  system. 
Example: 

See  also:     UpDirectory,  GoDirectory. 
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PownPirootOFy 


IDrawLine  (Apple,  C64,  ci28)  graphksl 

Function:       Draw,  clear,  or  recover  a  line  defined  by  two  arbitrary  endpoints. 

Parameters:    r3      XI  —  x-coordinate  of  first  endpoint  (word). 

rllL  Yl  —  y-coordinate  of  first  endpoint  (byte). 
r4      X2  —  x-coordinate  of  second  endpoint  (word), 
r  1 IH  Y2  —  y-coordinate  of  second  endpoint  (byte). 
St  MODE: 


n    c  Description 


1 

X 

recover  pixel  from  backKfound  screen  to  forejoound. 

0 

1 

set  Dixel  usine  dispBufferOn. 

0 

0 

clear  pixel  usine  dispBufferOn. 

where  (XI, Yl)  and  (X2J2)  are  the  two  endpoints  of  the  line. 


Uses:  if  n  is  set  (drawing,  not  recovering): 

dispBufferOn: 

bit  7  —  write  to  foreground  screen  if  set. 
bit  6  —  write  to  background  screen  if  set 

Returns:        status  register  (S)  unchanged 


Destroys:  Commodore 

a,  x,  y,  r3-rl3 


Apple 

a,  X,  y,  r3,  r4,  rll 


Description:  DrawLine  will  set,  clear,  or  recover  the  pixels  which  comprise  the  line  between 
two  arbitrary  endpoints.  Setting  a  pixel  sets  its  bit  value  to  one,  clearing  a  pixel 
sets  its  bit  value  to  zero,  and  recovering  a  pixel  copies  the  bit  value  from  the 
background  buffer  to  foreground  screen. 

DrawLine  uses  the  Bresenham  DDA  (Digital  Differential  Analyzer)  algorithm  to 
determine  the  proper  points  to  draw.  The  line  will  be  drawn  correctiy  regardless 
of  which  endpoint  is  used  for  (Xljl)  and  which  is  used  for  {X2J2).  In  fact, 
the  line  is  reversible:  the  same  line  will  be  drawn  even  if  the  endpoints  are 
swapped. 

The  carry  (c)  flag  and  sign  (n)  flag  in  the  processor  status  register  (s)  are  used  to 
pass  information  to  DrawLine.  The  following  tricks  can  be  used  to  set  or  clear 
these  flags  appropriately: 

♦  Use  sec  and  cic  to  set  or  clear  the  carry  (c)  flag. 

♦  Use  Ida       to  set  the  sign  (n)  flag. 

♦  Use  Ida  #0  to  clear  the  sign  (n)  flag. 


Note: 


Calculates  each  pixel  position  on  the  line  and  calls  DrawPoint  repeatedly. 


■PuwnDlrceteFy 


128:  Under  GEOS  128,  or*ing  DOUBLE  W  into  theX/  andX2  parameters  will 

automatically  double  the  x-position  in  8D-column  mode.  Or'ing  in  ADDl^W  will 
automatically  add  1  to  a  doubled  x-position,  (Refer  to  "GEOS  128  X-posiuon  and 
Bitmap  Doubling"  in  Chapten@gr@  for  more  information,) 

Example: 

See  also:       HorizontaILIne,VerticaILine,  InvertLine,  ImprintLine,  RecoverLine. 


flrawLine 


DrawPoint  (Apple,  C64,  cm) 


graphics 


Function: 
Parameters: 


Set,  clear,  or  recover  a  single  screen  point  (pixel). 

r3      XI  —  x-coordinate  of  pixel  (word), 
r  1 1 L  Y 1  —  y-coordinate  of  pixel  (byte). 
St  MODE: 


n 

c 

Description 

1 

X 

recover  pixel  from  backjo-ound  screen  to  foreground. 

0 

1 

set  pixel  using  dispBufferOn. 

0 

0 

clear  pixel  using  dispBufferOn. 

Uses: 

Returns: 
Destroys: 


Description: 


128: 


Example: 
See  also: 


where  (XI, Yl)  is  the  coordinate  of  the  point. 

when  setting  or  clearing  pixels: 
dispBufferOn: 

bit  7  —  write  to  foreground  screen  if  set. 

bit  6  —  write  to  background  screen  if  set 

r3,  rllL  unchanged. 

Commodore 
a,  X,  y,  r5-r6 

Applg 
a,  X,  y 

DrawPoint  will  set,  clear,  or  recover  a  single  pixel.  Setting  a  pixel  sets  its  bit 
value  to  one,  clearing  a  pixel  sets  its  bit  value  to  zero,  and  recovering  a  pixel 
copies  the  bit  value  from  die  background  buffer  to  foreground  screen. 

The  carry  (c)  flag  and  sign  (n)  flag  in  the  processor  status  register  (s)  are  used  to 
pass  information  to  DrawPoint.  The  following  tricks  can  be  used  to  set  or  clear 
these  flags  appropriately: 


•  Use  sec  and  cic  to  set  or  clear  the  carry  (c)  flag. 
Use  Ida  #[*!  to  set  the  sign  (n)  flag. 


Use  Ida  #0  to  clear  the  sign  (n)  flag: 


Under  CEOS  128,  orlng  DOUBLE^W  into  the  XI  will  automatically  double 
the  x-position  in  80-colunm  mode.  OFing  in  ADD1_W  will  automatically  add  1 
to  a  doubled  x-position.  (Refer  to  "CEOS  128  X-po?ition  and  Bitmap  Doubling" 
in  Chapter.@grtg)  for  more  information.) 


TestPoint,  DrawLine. 
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DrawSprite  (Apple,  C64,  ci28) 


sprite 


Function: 

Parameters: 

Returns: 

Alters: 

Destroys: 


Description: 


C64: 


C128: 


Apple: 


Example: 
See  also: 


Copy  a  64-byte  sprite  image  to  the  internal  data  buffer  that  is  used  for  drawing  the 
sprites. 

r3L    SPRITE  —  sprite  number  (byte). 

r4      DATAPTR  —  pointer  to  64-bytes  of  sprite  image  data  (word), 
nothing. 

internal  sprite  image. 

Commodore 
a,  y,  r5 

Applg 

a,  y 

DrawSprite  copies  64-bytes  of  sprite  image  data  to  the  internal  buffer  that  is 
used  for  drawing  the  sprites.  DrawSprite  does  not  affect  the  enabled/disabled 
status  of  a  sprite,  it  only  changes  the  image  definition. 

Although  there  are  eight  sprites  available,  an  application  should  limit  itself  to 
sprites  #2  through  #7  because  GEOS  reserves  sprite  #0  for  the  mouse  cursor  and 
sprite  #1  for  the  text  prompt. 

The  64  bytes  are  copied  to  the  VIC  sprite  data  area,  which  is  located  in  memory 
immediately  after  the  color  matrix.  The  size  information  byte  (byte  64)  is  unused 
by  GEOS  64  but  is  copied  to  the  data  area,  nonetheless.  A  SPRITE  value  of  $00 
can  be  used  to  change  the  shape  of  the  mouse  cursor. 

The  data  is  transferred  to  the  VIC  sprite  area  (regardless  of  the  current  graphics 
mode).  This  data  is  used  by  the  VIC  chip  in  40-column  mode  and  by  the  soft- 
sprite  handler  in  80-column  mode.  The  last  byte  (byte  64)  of  the  sprite  definition 
is  used  as  the  size  information  byte  by  the  soft-sprite  handler.  In  80-column 
mode,  the  sprite  is  not  visually  updated  until  the  next  time  the  soft-sprite  handler 
gets  control.  To  change  the  mouse  cursor,  the  application  can  use  a  SPRITE  value 
of  $00  in  40-column  mode  or  call  SetMsePic  in  80-column  mode  (doing  both  is 
a  simple  solution:  it  will  do  no  harm  regardless  of  the  graphics  mode). 

The  data  is  transferred  to  an  internal  sprite  area.  The  last  byte  (byte  64)  of  the 
sprite  definition  is  used  as  the  size  information  byte.  The  sprite  is  not  visually 
updated  until  the  next  time  the  soft-sprite  handler  gets  control.  The  soft-sprite 
handler  will  draw  sprite  #1  through  sprite  #7.  In  no  case  should  the  SPRITE 
parameter  be  $00;  a  value  of  $00  wUl  most  likely  trample  GEOS. 

The  INAUX_B  constant  may  be  or'ed  into  the  SPRITE  parameter  to  indicate 
that  the  DATAPTR  parameter  is  an  address  in  auxiliary  memory. 


GetSpriteData,  PosSprite,  EnablSprite,  DisablSprite,  InitSprite. 


DSdiv 


DSdiv  (Apple,  C64,  C128) 


math  I 


Function:       Signed  word-by-word  (double-precision)  division:  divides  one  two's  complement 
word  by  another  to  produce  a  signed  word  result. 

Parameters:    x       OPERANDI  —  zero-page  address  of  signed  word  dividend  (byte  pointer 

to  a  word  variable). 

y       0PERAND2  —  zero-page  address  of  signed  word  divisor  (byte  pointer  to 
a  word  variable). 

Note:  result  =  OPERANDI  (word)  I  OPERAND2(word). 

Returns:        y  unchanged. 

r8      the  fractional  remainder  (word). 

word  pointed  to  by  OPERANDI  equals  its  absolute  value. 

word  pointed  to  by  OPERANDI  contains  the  word  result. 

Commodore: 

X  unchanged 

Destroys:       a,  r9 


Apple: 

X 


Description:  DSdiv  is  a  signed,  two's  complement  word-by-word  division  routine  that 
divides  the  word  in  one  zero-page  pseudoregister  (the  dividend)  by  the  word  in 
another  (the  divisor)  to  produce  a  16-bit  word  signed  result  and  a  16-bit  word 
fractional  remainder  The  word  in  OPERANDI  is  divided  by  the  word  in 
OPERANDI  and  the  result  is  stored  as  a  word  back  in  OPERANDI  with  the 
remainder  in  r8. 

C64  &  C128:  The  remainder  is  always  positive  regardless  of  the  sign  of  the  dividend.  This  will 
cause  problems  with  some  mathematical  operations  that  expect  a  signed 
remainder.  The  following  code  fragment  will  fixe  this  problem: 


;NewDSdiv: 

call  as  you  would 

call  DSdiv.  Returns  a 

signed  remainder. 

Destroys  x! 

sign (remainder)  - 

sign  (dividend) 

NewDSdiv : 

Ida 

zpage,x 

;save  sign  of  dividend 

php 

Jsr 

DSdiv 

; divide  as  normal 

pip 

;then  get  back  sign  of  dividend  back 

bpl 

20$ 

/ignore  if  positive 

Idx 

«r8 

;else,  negate  remainder 

jsr 

Dnegate 

/(e.g.,  -10/9  -  -1  rem  -1) 

20$: 

rts 

The  sign  of  the  remainder  is  the  same  as  the  sign  of  the  dividend. 

Because  r8  and  r9  are  used  in  the  division  process,  they  cannot  be  used  to  hold 
the  operands. 


Apple: 
Note: 
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DSdiv 


Although  dividing  by  zero  is  an  undefined  mathematical  operation,  DSdiv  makes 
no  attempt  to  flag  this  as  an  error  condition  and  simply  returns  incorrect  results.  If 
the  divisor  might  be  zero,  the  application  should  check  for  this  situation  before 
dividing: 


Example: 
SeeAlso: 


10$: 


Ida  zpage,y  ;get  low  byte  of  divisor 

ora  zpage+l,y  ;get  high  byte  of  divisor 

bne  10$  ;if  either  non-zero,  go  divide 

jmp  DivideByZero  ;else,  flag  error 

jmp  DSdiv  ; divide  (DSdiv  will  rts) 


Ddiv,  DMult,  BMult,  BBMuIt,  DivideBySeven. 
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DShiftLeft 


DShiftLeft  (Apple,  C64,  C128) 


math 


Function: 
Parameters: 

Returns: 


Arithmetically  left-shift  a  zero-page  word 

X 

y 


OPERAND  —  address  of  the  zero-page  word  to  shift  (byte  pointer  to  a 
word  variable). 

COUNT  —  number  of  times  to  shift  the  word  left  (byte). 


a,  X  unchanged 
y  #$ff 

St      c  (carry  flag)  is  set  with  last  bit  shifted  out  of  word. 

zero  page  address  pointed  to  hy OPERAND  contains  the  shifted  word. 


Destroys:  nothing 


Description: 


Note: 

Example: 

SeeAlso: 


DShiftLeft  is  a  double-precision  math  routine  that  arithmetically  left-shifts  a  16- 
bit  zero-page  word  (low/high  order).  The  absolute  address  of  the  word  is  passed 
in  X  and  the  number  of  times  to  shift  the  word  is  passed  in  y.  Zeros  are  shifted 
into  the  low-order  bit 

An  arithmetic  left-shift  is  useful  for  quickly  multiplying  a  value  by  a  power  of 
two.  One  left-shift  will  multiply  by  two,  two  left-shifts  will  multiply  by  four, 
three  left-shifts  will  multiply  by  eight,  and  so  on:  value  =  value  ♦  l^ount^ 

If  a  COUNT  of  $00  is  specified,  the  the  word  will  not  be  shifted. 


DSh:ftRight. 
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DShiftRight 


DShiftRight  (Apple,  C64,  C128) 


math 


Function: 
Parameters: 

Returns: 


Arithmetically  right-shift  a  zero-page  word. 

X 

y 


OPERAND  —  zero-page  address  of  word  to  shift  (byte  pointer  to  a  word 
variable). 

COUNT  —  number  of  times  to  shift  the  word  right  (byte). 


a,  X  unchanged 
y  #$ff 

St  c  (carry  flag)  is  set  with  last  bit  shifted  out  of  word, 
register  pointed  to  by  OPERAND  contains  the  shifted  word 


Destroys:  nothing 


Description: 


Example: 
SeeAlso: 


DShiftRight  is  a  double-precision  routine  that  arithn^tically  right-shifts  a  16-bit 
zero-page  word  (low/high  order).  The  address  of  the  word  is  passed  in  x  and  the 
number  of  times  to  shift  the  word  is  passed  in  y.  Zeros  are  shifted  into  the  high- 
order  bit. 

An  arithmetic  right-shift  is  useful  for  quickly  dividing  a  value  by  a  power  of  two. 
One  left-shift  will  divide  by  two,  two  left-shifts  will  divide  by  four,  three  left- 
shifts  will  divide  by  eight,  and  so  on:  value  =  value  /  2^^"^^ 


DShiftLeft. 
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EnableProcess 


EnableProcess  (Apple,  C64,  ci28) 


process! 


Function: 
Parameters: 

Returns: 


Description: 


Example: 


Makes  a  process  tunable  immediately. 

X       PROCESS  —  number  of  process  (0  -  n-l,  where  n  is  the  number  of 
processes  in  the  table)  (byte). 


unchanged. 


Destroys:  a 


EnableProcess  forces  a  process  to  become  runable  on  the  next  pass  through 
MainLoop,  independent  of  its  timer  value. 

EnableProcess  merely  sets  the  runable  flag  in  the  hidden  process  table.  When 
MainLoop  encounters  an  unblocked  process  with  this  flag  set,  it  will  attempt  to 
generate  an  event  just  as  if  the  timer  had  decremented  to  zero. 

EnableProcess  has  no  priveleged  status  and  cannot  override  a  blocked  process.* 
However,  because  it  doesn't  depend  on  or  affect  the  current  timer  value,  the 
process  can  become  runable  even  with  a  frozen  timer. 

EnableProcess  is  useful  for  making  sure  a  process  runs  at  least  once, 
regardless  of  the  initialized  value  of  the  countdown  timer.  It  is  also  useful  for 
creatingapplication-defined  events  which  run  off  of  MainLoop:  a  special  process 
can  be  reserved  in  the  data  structure  but  never  started  with  RestartProcess.  Any 
time  the  desired  event-state  is  detected,  a  call  to  EnableProcess  will  generate  an 
event  on  the  next  pass  through  MainLoop.  EnableProcess  can  be  called  from 
Interrupt  Level,  which  allows  a  condition  to  be  detected  at  Interrupt  Level  but 
processed  during  MainLoop. 


See  also:       InitProcesses,  RestartProcess,  UnfreezeProcess,  UnblockProcess. 
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EnablSprite 


EnablSprite  (Apple,  C64,  cns) 


sprite 


Function: 

Parameters: 

Returns: 

Alters: 

Destroys: 

Description: 


Example: 
See  also: 


Enable  a  sprite  so  that  it  becomes  visible. 

r3L     SPRITE  —  sprite  number  (byte). 

nothing. 

mobenble 

a,  X 

EnablSprite  enables  a  sprite  so  that  it  becomes  visible.  Although  there  are  eight 
sprites  available,  an  application  should  only  directly  enable  sprites  #2  through  #7 
with  EnablSprite.  Sprite  #0  (the  mouse  pointer)  is  enabled  through  MouseOn 
and  StartMouseMode,  and  sprite  #1  (the  text  cursor)  should  be  enabled  with 
PromptOn. 


DisablSprite,  MouseUp,  PromptOn,  DrawSprite,  GetSpriteData, 
PosSprite,  InitSprite. 
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EnterDeskTop 


EnterPeskTop  (Apple,  C64,  cus) 

Function:       Standard  application  exit  to  GEOS  dcskTop, 

Parameters:  none. 

Returns:         never  retutms  to  application. 

Description:  An  application  calls  EnterDeskTop  when  it  wants  to  exit  to  the  GEOS  deskTop- 
EnterDeskTop  takes  no  parameters  and  looks  for  a  copy  of  the  file 
DESK  TOP  on  each  drive.  Later  versions  of  GEOS  are  only  compatible  witii 
the  correspondingly  later  revision  of  the  deskTop  and  will  check  the  version 
number  in  the  permanent  name  string  of  the  DESK  TOP  file  to  ensure  that  it  is 
in  fact  a  newer  version.  If  after  all  drives  are  searched  no  valid  copy  of  the 
deskTop  is  found,  EnterDeskTop  will  prompt  the  user  to  insert  a  disk  witii  a 
copy  of  the  deskTop  on  it. 

C64  &  C128:  EnterDeskTop  will  first  search  a  RAMdisk  for  a  copy  of  the  deskTop  to  ensure 
the  fastest  loading  tin^e. 

Apple:  EnterDeskTop  will  first  search  all  non-removable  media  devices  (RAMdisk, 

hard  disk,  etc.)  for  a  copy  of  the  deskTop,  then  other  devices  (floppy  disk 
devices).  These  devices  are  searched  in  the  order  that  they  appear  on  the  deskTop, 
which  corresponds  to  their  order  in  the  expansion  slots:  a  device  in  slot  seven  will 
be  searched  before  a  device  in  slot  six. 

Example: 

See  also:        RstrAppl,  GetFile. 


high-level  disk 
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EnterTurbo 


EnterTurbo  (C64,  ci28) 


verylow-level  disk  I 


Function: 

Parameters: 

Uses: 

Returns: 

Destroys: 

Calls: 

Description: 


Activate  disk  drive  turbo  mode, 
none. 


Apple: 
Example: 
See  also: 


curDrive 
curType 


currently  active  disk  drive. 

vl.3+:  checks  disk  type  because  not  all  use  turbo  software. 


X 

a,  y. 


error  ($00  =  no  error). 


EnterTurbo  activates  the  turbo  software  in  the  current  drive.  If  the  turbo 
software  has  not  yet  been  downloaded  to  the  drive,  EnterTurbo  will  download 
it.  The  turbo  software  allows  GEOS  to  perform  high-speed  serial  disk  access. 

EnterTurbo  treats  diflferent  drive  types  appropriately.  A  RAMdisk,  for  example, 
does  not  use  turbo  code  so  EnterTurbo  will  not  attempt  to  download  the  turbo 
software. 

The  very-low  level  Commodore  GEOS  read/write  routines,  such  as  ReadBlock, 
WriteBlock,  VerWriteBIock,  and  ReadLink,  expect  the  turbo  software  to 
be  active.  Call  EnterTurbo  before  calling  one  of  these  routines. 

Apple  GEOS  has  no  EnterTurbo  equivalent 

See  WriteBlock. 

ExitTurbo,  PurgeTurbo. 
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-&ftt6rTurbo 


EraseCharacter  (Apple) 


text 


Function:       Erase  a  character  from  the  screen,  accounting  for  the  current  font  and  style 
attributes. 

Parameters:    a       CHAR  —  character  code  of  character  to  erase  (byte). 

r  1 1    XPOS  —  x-coordinate  of  left  of  character  (word), 
r  1 H    YPOS  —  y-coordinate  of  character  baseline  (word). 

Uses:  same  as  PutChar. 

Returns:        rll,  rlH  unchanged. 

Alters:  lastWidth  width  of  character  just  erased 

Destroys:  Commodore 

rlL,  r2-rl0,  rl2,  rl3,  a,  x,  y. 

Apple 

rlL,  r2,  a,  x,  y. 


Description:   EraseCharacter  calculates  the  widdi  of  the  character  and  erases  it  from  the 
screen  using  the  USELAST  character  and  SmallPutChar. 

Note:  Uses  currentMode  to  calculate  the  character  width.  When  deleting  multiple 

characters,  the  application  will  need  to  take  this  into  account  when  backspacing 
from  one  style  to  another.  Also,  does  not  always  work  with  characters  that  are 
both  bolded  and  outlined  because  not  all  fonts  have  a  wide  enough  USELAST 
character. 


See  also: 
Example: 


SmallPutChar,  PutChar,  PutString. 


ExitTurbo 


ExitTurbO  (C64,  cm)  very  Iow>level  disk] 


Function:       Deactivate  disk  drive  turbo  mode. 
Parameters:  none. 

Uses :  cur  Drive  currently  active  disk  drive. 

Returns:        x         error  ($00  =  no  error). 
Destroys:       a,  y. 

Description:  ExitTurbo  deactivates  the  turbo  software  in  the  current  drive  so  that  the  serial 
bus  may  access  another  device.  SetDevice  automatically  calls  this  before 
changing  devices. 

Note:  If  the  turbo  software  has  not  been  downloaded  or  is  already  inactive,  ExitTurbo 

will  do  nothing. 

Apple:  Apple  GEOS  has  no  ExitTurbo  equivalent. 

Example:       See  WriteBIock. 

See  also:       EnterTurbo,  PurgeTurbo. 
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FastDelFile 


FastPelFile  (C64,  cm) 


mid-level  disk 


Function: 
Parameters: 

Uses: 


Returns: 

Destroys: 

Description: 


Note: 


Special  Commodore  version  of  DeleteFile  that  quickly  deletes  a  sequential  file 
when  the  track/sector  table  is  available. 

r  0        FILENAME  —  pointer  to  null-terminated  file  name  (word), 
r3        TSTABLE  —  pointer  to  track  and  sector  table  of  file,  usually  points  to 
fileTrScTab  (word). 


curDrive. 

curType 

curDirHead 

dir2Headt 

dir3Headt 


GEOS  64  vl.3  and  later:  for  detecting  REU  shadowing, 
BAM  updated  to  reflect  newly  freed  blocks. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


X         error  ($00  =  no  error), 
a,  y,  rO,  r9. 

FastDelFile  quickly  deletes  a  sequential  file  by  taking  advantange  of  an  already 
existing  tracl^sector  table.  It  first  removes  the  directory  entry  determined  by 
FILENAME  and  calls  FreeBIock  for  each  block  in  a  track/sector  table  at 
TSTABLE.  The  track/sector  table  is  in  the  standard  format,  such  as  that  returned 
from  ReadFile,  where  every  two-byte  entry  constitutes  a  track  and  sector.  A 
track  number  of  $00  terminates  the  table. 

FastDelFile  is  fast  because  it  does  not  need  to  follow  the  chain  of  sectors  to 
delete  the  individual  blocks.  It  can  do  most  of  the  deletion  by  manipulating  the 
BAM  in  memory  then  writing  it  out  with  a  call  to  PutDirHead  when  done. 

FastDelFile  will  not  properly  delete  VLIR  files  without  considerable  work  on 
the  application's  part.  Because  there  is  no  easy  way  to  build  a  track/sector  table 
that  contains  all  the  blocks  in  all  the  records  of  a  VLIR  file,  it  is  best  to  use 
DeleteFile  or  FreeFile  for  deleting  VLIR  files  or  DeleteRecord  for  deleting  a 
single  record. 

FastDelFile  calls  GetDirHead  before  freeing  any  blocks.  This  will  overwrite 
any  BAM  and  directory  header  in  memory. 

FastDelFile  can  be  used  to  remove  a  directory  entry  without  actually  freeing  any 
blocks  in  the  file  by  passing  a  dummy  track/sector  table,  where  the  first  byte 
(track  number)  is  $00  signifying  the  end  of  the  table: 

;Pass:  rJD      pointer  to  filename 

E>eleteDirEntry : 

LoadW       r3,#NullTrScTable  ;pass  dummy  table 

jmp  FastDelFile  ; delete  dir  entry 

;        never  get  here  —  FastDel  returns  to  caller 

This  will  also  work  correctly  with  a  VLIR  file. 

For  freeing  (deleting)  all  the  blocks  in  a  file  widiout  removing  the  directory  entry, 
refer  to  FreeFile. 
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Apple:  Apple  GEOS  has  no  FastDelFile  equivalent  because  the  ProDOS  blocks  are  not 

linked  with  internal  forward  pointers.  Use  DeleteFile. 

Example: 


Read  sequential  file  into  memory  and  then  delete  it 
from  disk 


;Pass:  r6      pointer  to  filename 

r7      where  to  put  data 


r2      size  of  buffer  (max  size  of  file) 


; Returns: 

X  error  code 


Destroys: 

a,  y,  r0-r9 


Implementation : 

Call  Findfile  to  get  the  directory  entry  of  the 
file  to  load/delete.  We  pass  the  directory  entry 
to  GetFHdrlnfo  to  get  the  GEOS  header  block.  We 
check  the  header  to  ensure  we* re  not  trying  to 
read  in  a  VLIR  file.  After  GetFHdrlnfo,  the 
parameters  are  already  set  up  correctly  to  call 
ReadFile  (f ileTrScTab+0, f ileTrScTab+1  contains 
header  block  and  rl  contains  first  data  block) . 
Readfile  reads  in  the  file's  blocks,  building  out 
the  remainder  of  the  fileTrScTab,  which  we  pass 
to  FastDelFile  to  free  all  blocks  in  the  file 
(including  the  file  header  block,  which  is  the 


first 

entry  in  the  table)  . 

ReadAndDelete: 

MoveW 

r6,r0 

;save  pointer  for  FastDel 

Jsr 

FindFile 

;find  file  on  disk 

txa 

;set  status  flags 

bne 

96$ 

; branch  on  error 

LoadW 

r9,dirEntryBuf 

;get  directory  entry 

jsr 

GetFHdrlnfo 

;get  GEOS  file  header 

txa 

;set  status  flags 

bne 

96$ 

/branch  on  error 

Ida 

fileHeader+OFF  GSTRUCT  TYPE 

cmp 

#VLIR 

; check  filet ype 

bne 

10$ 

; branch  if  not  VLIR 

Idx 

#STRUCT_MISMAT 

; can't  load  VLIR 

bne 

96$ 

/branch  always  for  error 

10$: 

jsr 

ReadFile 

;read  in  file 

txa 

/else  set  status  flags 

bne 

96$ 

/branch  on  other  error 

20$: 

LoadW 

r3,#fileTrScTab 

/track/sector  tbl 

jsr 

FastDelFile 

/file  read  OK,  delete  it! 

d6$ 

rts 

/error  in  x 

See  also:       FreeFile,  DeleteFile. 
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FdFTypesInPir  (Apple) 


high-level  disk 


Function:       Special  Apple  GEOS  version  of  FindFTypes  that  will  build  the  filename  list 
using  a  directory  other  than  the  current  directory. 

Parameters:    r6        BUFFER  —  pointer  to  buffer  for  building-out  file  list;  allow  16  bytes 

for  each  entry  in  the  list  (word), 
r  1 0       PERMN AME  —  pointer  to  permanent  name  string  to  match  or  $0000  to 

ignore  permanent  name  string  (word). 
r7H      MAXETLES  —  maximum  number  of  filenames  to  retum,  usually  used 

to  prevent  overwriting  end  of  BUFFER  (must  be  less  than  127).  If 

INAUX^B  is  bitwise-or'ed  into  this  parameter,  BUFFER  will  be 

treated  as'an  address  in  auxiliary  memory. 
r7L       FILETYPE  —  GEOS  file  type  to  search  for  or  WILDCARD,  which 

will  match  all  types  except  subdirectories  (byte), 
rl        DIRBLKNO  —  block  number  of  directory  to  search  (word). 

curDrive 

X         error  ($00  =  no  error). 

r7H      decremented  once  for  each  file  name  (Apple  GEOS:  high-bit  is  always 
cleared). 

diskBIkBuf        used  as  temporary  buffer  for  directory  blocks, 
a,  y,  rO-r2L,  r4-r6. 

FdFTypesInDir  performs  the  same  action  as  FindFTypes,  except  that 
DIRBLKNO  temporarily  becomes  the  current  directory.  The  current  directory  is 
restored  before  returning. 

The  data  area  at  BUFFER,  where  the  list  is  built-out,  must  be  large  enough  to 
accomodate  MAXFILES  filenames  of  16  bytes  each. 

C64  &  C128:  Commodore  GEOS  does  not  support  a  hierarchical  file  system. 
Example: 

See  also:        FindFTypes,  FndFillnDir. 


Uses: 
Returns: 

Alters: 

Destroys: 

Description: 


CONAkoklisi  SAL 


FetchRAM 


FetchRAM  (C64  vi.3  &  ci28) 


memoryl 


Function: 
Parameters: 

Returns: 

Destroys: 
Description: 


Note: 
Example: 
See  also: 


Primitive  for  transferring  data  from  an  REU. 

rO  CBMDST  —  address  in  Commodore  to  put  data  (word), 

r  1  REUSRC  —  address  in  REU  bank  to  start  reading  (word). 

r2  COUNT — number  of  bytes  to  fetch  (word). 

r3L  REUS ANK  —  REU  bank  number  to  fetch  from  (byte). 


r0-r3  unchanged. 
X       error  code: 


a 

y 


$00  (no  error)  or  DEV_NOT_FOUND  if  REUBANK 
or  REU  not  available.  ~ 
REU  status  byte  and'ed  with  $60  ($40  =  successful  fetch). 


FetchRAM  moves  a  block  of  data  from  an  REU  bank  into  Commodore 
memory.  This  routine  is  a  "use  at  your  own  risk"  low-level  GEOS  primitive 

FetchRAM  uses  the  DoRAMOp  primitive  by  calling  it  with  a  CMD  parameter 
of  %10010001. 

Refer  to  DoRAMOp  for  notes  and  warnings. 


StashRAM,  SwapRAM,  VerifyRAM,  DoRAMOp,  MoveBData. 
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FillRam 


FillRam,  i  FillRam  (Apple,  C64,  ci28) 


memory] 


Function: 
Parameters: 


Returns: 

Destroys: 

Description: 

Note: 
Example: 
See  also: 


pais  a  region  of  memory  with  a  repeating  byte  value. 
Nomial: 

rO      COUNT  —  number  of  bytes  to  clear  (0  -  64K)  (word), 
r  1      ADDR  — ^address  of  area  to  clear  (word). 
r2L    PILL  —  byte  value  to  fill  with  (byte). 

Inline: 

.word  CXDUNT — number  of  bytes  to  clear  (0  -  64K)  (word), 

.word  ADDR  — address  of  area  to  clear  (word), 

.byte  PELL  —  byte  value  to  fill  with  (byte). 

r2L  unchanged. 

a,  y,  rO,  rl 

FillRam  fills  COUNT  bytes  starting  at  ADDR  with  the  PILL  byte.  This  routine 
is  useful  for  initializing  a  block  of  memory  to  some  non-zero  or  variable  value 
(for  filling  a  region  with  $00,  use  ClearRam). 

Do  not  use  FillRam  to  initialize  rO-r2L. 


ClearRam,  InitRam. 
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FindBAMBit 


FindBAMBit  (C64,  ci28) 


m  id.level  disk 


Function: 
Parameters: 

Uses: 


Returns: 


Destroys: 


Description: 


Get  disk  block  allocation  status. 

r6L      TRACK  —track  number  of  block  (byte). 
r6H      SECTOR  —  sector  number  of  block  (byte). 


curDrive 
curDirHead 
dir2Headt 
dirSHeadt 


this  buffer  must  contain  the  cunent  directory  header. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use, 

St        z  flag  reflects  allocation  status  (1  =  free ;  0  =  allocated). 
r6  unchanged 

1541  drives  onlv: 

X         offset  from  curDirHead  for  BAM  byte. 
r8H      mask  for  isolating  BAM  bit. 
a         BAM  byte  masked  with  r8H. 

r7H      offset  from  curDirHead  of  byte  that  holds  free  blocks  on  track  total. 

non-1541  drives: 
a,  y,  r7H.  r8H. 

1541  drives: 

y  (a,  r7H,  and  rSH  all  contain  useful  values). 

FindBAMBit  accesses  the  BAM  of  the  current  disk  'in  curDirHead)  and 
returns  the  allocation  status  of  a  particular  block.  If  the  BAM  bit  is  zero,  then  the 
block  is  in-use;  if  the  BAM  bit  is  one,  then  the  block  is  free.  FindBAMBit 
returns  with  the  z  flag  set  to  reflect  the  status  of  the  BAM  so  that  a  subsequent 
bne  or  beq  branch  instructions  can  test  the  status  of  a  block  after  calling 
FindBAMBit: 


Note: 


Apple: 
Example: 


bne 
beq 


BlocklsFree 

or- 

BlocklnUse 


; branch  if  block  is  free 
;branch  if  block  is  in-use 


FindBAMBit  will  return  the  allocation  status  of  a  block  on  any  disk  device, 
even  those  with  large  or  multiple  BAMs  (such  as  the  1571  and  1581  disk  drives). 
Only  the  1541  driver,  however,  will  return  useful  information  in  a,  y,  r7H,  and 
r8H.  For  an  example  of  using  these  extra  1541  return  values,  refer  to 
AIlocateBlock. 


See  FindVBMBit. 


LoadB 
LoadB 
jsr 
beq 


r6L,#TRACK 
r6H,#SECT0R 
FindBAMBit 
BlocklnUse 


;  get  track  and  sector  number 

;  get  allocation  status 
;  branch  if  already  in  use 
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FindBAMBit 

See  also:       FindVBMBit,  AIlocateBIock,  FreeBIock.  GetDirHead,  PutDirHead. 
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FindFile 


FindFilejAppie,  C64,  ci28) 


high-level  disk 


Function: 
Parameters: 

Uses: 


Returns: 


Alters: 

Destroys: 
Description: 


Search  for  a  particular  file  in  the  current  directory. 

r6  FILENAME  —  pointer  to  null-terminated  name  of  file  of  a  maximum  of 
ENTRY^SIZE  bytes  (not  counting  null  terminator).  (Apple  GEOS: 
must  be  in  main  memory.)  (word). 

curDrive 

Commp^^Qre; 
curType 

Applg: 

curKBlkno 


GEOS  64  vl.3  and  later:  for  detecting  REU  shadowing. 


current  directory. 
X  error  ($(X)  =  no  error). 

rl        block  number  (Commodore  track/sector)  of  directory  block  containing 
entry, 

r5        pointer  into  diskBIRBuf  to  start  of  directory  entry. 


diskBIkBuf 
dirEntryBuf 

a,  y,  r4,  r6. 


contains  directory  block  where  FILENAME  found, 
directory  entry  of  file  if  found. 


Given  a  null-terminated  filename,  FindFile  searches  through  the  current 
directory  and  returns  the  directory  entry  in  dirEntryBuf.  If  the  file  specified 
with  FILENAME  is  not  found,  a  FILE_NOT_FOUND  error  is  returned. 


C64  &  C128:  Since  Commodore  GEOS  does  not  support  a  hierarchical  file  systeni,  the  "current 
directory'*  is  actually  the  entire  disk.  The  directory  entry  is  deleted  by  setting  its 
OFF^CFILE^TYPE  byte  to  $00. 


Apple: 

Example: 
See  also: 


Only  the  current  directory,  the  directory  specified  by  curKBlkno,  is  searched. 
To  search  a  directory  other  than  the  current  one,  use  FndFillnDir. 


FndFillnDir,  GetlstDirEntry,  GetNxtDirEntry,  FindFTypes. 
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FindFTypes 


FindFTypes  (Apple,  C64,  cns) 


high-level  dlskl 


Function: 
Parameters: 


Uses: 


Returns: 

Alters: 
Destroys: 


BuUds  a  list  of  files  of  a  particular  GEOS  type  from  the  current  directory, 

r6        BUFFER' —  pointer  to  buffer  for  building-out  file  list;  allow 

.  ENTRY_SIZE+1  bytes  for  each  entry  in  the  list  (word), 
r  1 0       PERMN AME  —  pointer  to  permanent  name  string  to  match  or  $0000  to 
ignore  permanent  name  string  (word). 

Commodore: 

r7H      MAXFILES  —  maximum  number  of  filenames  to  return,  usually  used 

to  prevent  overwriting  buffer. 
r7L      FILETYPE  —  GEOS  file  type  to  search  for  (byte). 


Applg; 
r7H 


r7L 


MAXFILES  —  maximum  number  of  filenames  to  return,  usually  used 
to  prevent  overwriting  end  of  BUFFER  (must  be  less  than  127).  If 
INAUX_B  is  bitwise-or'ed  into  this  parameter,  BUFFER  will  be 
treated  as"an  address  in  auxiliary  memory. 

FILETYPE  —  GEOS  file  type  to  search  for  or  WILDCARD,  which 
will  match  all  types  except  subdirectories  (byte). 


curDrive 

Commodore: 
curType 

Apple: 

curKBIkno 


GEOS  64  V  1.3  and  later  for  detecting  REU  shadowing. 


current  directory. 


X         error  ($00  =  no  error). 

r7H      decremented  once  for  each  file  name  (Apple  GEOS:  high-bit  is  always 
cleared). 


diskBlkBuf 


used  as  temporary  buffer  for  directory  blocks. 


CpqTmQ(jorg; 
a,  y,  rO-r2L,  r4,  r6. 

Apple; 

a,  y,  rO-r2L,  r4-r6. 

Description:   FindFTypes  build  a  list  of  files  that  match  a  particular  GEOS  file  type  and, 
optionally,  a  specific  permanent  name  string. 

The  data  area  at  BUFFER,  where  the  list  is  built-out,  must  be  large  enough  to 
accomodate  MAXFILES  filenames  of  ENTRY_SIZE+1  bytes  each. 

FindFTypes  first  clears  enough  of  the  area  at  BUFFER  to  hold  MAXFILES 
filenames  tiien  calls  GetlstDirEntry  and  GetNxtDirEntry  to  go  tiirough  each 
directory  entry  in  the  current  directory.  When  the  GEOS  file  type  of  a  directory 
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FIndFTypes 


entry  matches  the  FILETYPE  parameter,  FindFTypes  goes  on  to  check  for  a 
matching  permanent  name  string. 

If  the  PERMNAME  parameter  is  $0000,  then  this  check  is  bypassed  and  the 
filename  is  added  to  the  list.  If  the  PERMNAME  parameter  is  non-zero,  the  null- 
terminated  string  it  points  to  is  checked,  character-by-character,  against  the 
permanent  name  string  in  the  file's  header  block.  Although  the  permanent  name 
string  in  the  GEOS  file  header  is  16  characters  long,  the  comparison  only  extends 
to  the  character  before  the  null-terminator  in  the  string  at  PERMNAME. 

Since  permanent  name  strings  typically  end  with  Vxjc,  where  xjc  is  a  version 
number  (e.g.,  2.1),  a  shorter  string  can  be  passed  so  that  the  specific  version 
number  is  ignored  For  example,  a  program  called  geoQuiz  version  1.3  might  use 
"geoQuiz  V1.3"  as  the  permanent  name  string  it  gives  its  data  files.  When 
geoQuiz  version  3.0  goes  searching  for  its  data  files,  it  can  pass  a  PERMNAME 
string  of  "geoQuiz  V"  so  data  files  for  all  versions  of  the  program  will  be  added  to 
the  list 


When  a  match  is  found,  the  filename  is  copied  into  the  list  at  BUFFER.  The 
filenames  are  placed  in  tJie  buffer  as  they  are  found  (the  same  order  they  appear 
on  the  pages  of  the  deskTop  notepad).  With  a  small  buffer,  matching  files  on 
higher-numbered  pages  may  never  get  added  to  the  list. 

C64  &  C128:  Since  Coninxxiore  GEOS  does  not  support  a  hierarchical  file  system,  the  "current 
directory"  is  actually  the  entire  disk.  The  filenames  appear  in  the  list  null- 
terminated  even  though  they  are  padded  with  $aO  in  the  directory. 

Apple:  Only  the  current  directory  specified  by  curKBIkno  is  searched.  To  search  a 

directory  other  than  the  current  one,  use  FdFTypesInDir.  The  filenames  in  the 
list  are  null-terminated 


To  search  for  subdirectories  in  the  current  directory,  pass  PRO  DIR  as  the 
FILETYPE.  When  searching  for  directories,  the  permanent  string  check  is 
bypassed  To  match  all  file  types  except  subdirectories,  pass  WILDCARD  as 
the  FILETYPE  and  $0000  for  the  PERMSTRING  parameter. 

A  filename  list  created  with  FindFTypes  can  be  sorted  alphabetically  with  a  call 
to  SortAIpha. 

Example: 

See  also:        FdFTypesInDir,  FindFile,  GetlstDirEntry,  GetNxtDirEntry. 
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FindVBMBitJAppie) 


mid-level  diskl 


Function: 


Uses: 


Returns: 


Alters: 


Destroys: 


Get  disk  block  allocation  status. 


Parameters:  r6 


BLOCK  —  block  number  (word). 


VBMBlknot 
curVBlknot 
VBMchangedt 
numVBMBIkst 


first  VBM  block  starts  here;  set  initially  by  OpenDisk 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 

X  error  ($00  =  no  error). 

St  z  flag  reflects  allocation  status  (1  =  fiee;  0  =  allocated). 

r8H  mask  for  isolating  VBM  bit 

r7  offset  to  BAM  byte  in  current  VBM  block. 

a  BAM  byte  masked  witfi  r8H. 

r6  unchanged. 


curVBlknot 
VBMchangedt 


Block  that  contains  the  VBM  bit  for  BLOCK. 
changed  to  FALSE  if  VBM  cache  flushed. 


^used  internally  by  GEOS  disk  routines:  applications  generally  don't  use. 

y 


Description:  FindVBMBit  accesses  the  VBM  of  the  current  disk  and  returns  the  allocation 
status  of  a  particular  block.  If  the  VBM  bit  is  zero,  then  the  block  is  in-use;  if  the 
VBM  bit  is  one,  tiien  the  block  is  free.  FindVBMBit  returns  witir  tiie  z  flag  set 
to  reflect  the  status  of  the  BAM  bit  so  tiiat  a  subsequent  bne  or  beq  branch 
instructions  can  test  the  status  of  a  block  after  calling  FindVBMBit: 


bne 
beq 


BloclcIsFree 

or- 

BlocklnUse 


C64  &C128:  See  FindBAMBit. 


Example: 


LoadW 

jsr 

cpx 

bne 

tay 

beq 


r6,#BL0CK 
FindVBMBit 
#NO_ERROR 
diskError 

BlocklnUse 


/branch  if  block  is  free 
/branch  if  block  is  in-use 


get  block  number 
get  allocation  status 
check  for  error 
branch  on  error 
check  block  status 
branch  if  block  in  use 


See  also:       FindBAMBit,  AlIocateBlock,  FreeBlock,  GetDirHead,  PutDirHead. 
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Firstlnit  (Apple,  C64,  cm) 


internal 


Function:  Simulates  portions  of  the  GEOS  coldstart  procedure  without  actually  rebooting 
GEOS  or  destroying  the  application  in  memory. 

Parameters:  none 

Returns:  GEOS  variables  and  system  hardware  in  a  coldstart  state;  stack  and  application 
space  unaffected 

Destroys:       a,  x,  y,  r0-r2 

Description:  Firstlnit  is  part  of  the  GEOS  coldstart  procedure.  It  initializes  nearly  all  GEOS 
variables  and  data  structures  (both  global  and  local),  including  those  which  are 
usually  only  done  once,  when  GEOS  is  first  booted,  such  as  setting  the 
configuration  variables  to  a  default,  power-up  state. 

GEOS  calls  this  routine  intemally.  Applications  will  not  find  it  especially  useful. 

Note:  The  GEOS  font  variables  are  not  reset  by  Firstlnit;  a  call  to  UseSystemFont 

may  be  necessary. 

See  also:       WarmStart,  StartAppl. 
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FndFillnDir  (Apple) 


high-level  disk! 


Function: 

Parameters: 

Uses: 
Returns: 

Alters: 

Destroys: 
Description: 


Special  Apple  GEOS  version  of  FindFile  that  will  search  for  a  file  in  a  directory 
other  than  die  current  directory. 

r6        FILENAME  —  pointer  to  nuU-terminated  name  of  file  (word), 
rl        DERBLKNO  —  block  number  of  directory  to  search  (word). 

curDrive 

X         error  ($00  =  no  error). 

rl        block  number  of  directory  block  containing  entry. 
rS        pointer  into  diskBIkBuf  to  start  of  directory  entry. 


diskBIkBuf 
dirEntryBuf 

a,  y,  r4-r6. 


contains  directory  block  where  FILENAME  found, 
directory  entry  of  file  if  found. 


C64  &  C128: 
Example: 
See  also: 


FndFillnDir  performs  the  same  action  as  FindFile,  except  tiiat  DIRBLKNO 
temporarily  becomes  the  current  directory.  The  current  directory  is  restored  before 
returning.  FndFillnDir  returns  the  directory  entry  in  dirEntryBuf.  If  the  file 
specified  with  FILENAME  is  not  found  in  the  DIRBLKNO  directory,  a 
FILE^NOT^FOUND  error  is  returned. 

Commodore  GEOS  does  not  support  a  hierarchical  file  system. 


FindFile,  FdFTypesInDir,  GoDirectory. 
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FollowChain  (C64,  cus) 


mid-level  disk 


Function: 
Parameters: 

Uses: 
Returns: 

Alters: 

Destroys: 

Description: 


Apple: 


Example; 


Follow  a  chain  of  Commodore  disk  blocks,  building  out  a  track/sector  table. 

rlL      START^TRACK  — track  number  of  starting  block  (byte), 
rlH      START^SEC  —  sector  number  of  starting  block  (byte). 
r3        TSTABLE  —  pointer  to  buffer  for  building  out  track  and  sector  table  of 
chain,  usually  points  to  fileTrScTab  (word). 


curDrive. 
curType 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing. 


X  error  ($00  =  no  error).  , 
r3  unchanged. 

track/sector  built-out  in  buffer  pointed  to  by  TSTABLE. 


diskBlkBuf 
a,  y,  rl,  r4. 


used  for  temporary  block  storage. 


FollowChain  constructs  a  track/sector  table  for  a  list  of  chained  blocks  on  the 
disk.  It  starts  with  the  block  passed  in  START JTR  and  START^SC  and  follows 
the  links  until  it  encounters  the  last  block  in  the  chain.  Each  block  (including  the 
first  block  at  START  JTR,  START  JSC )  becomes  a  part  of  the  track/sector  table. 

Commodore  disk  blocks  are  linked  together  with  track/sector  pointers.  The  first 
two  bytes  of  each  block  represent  a  track/sector  pointer  to  die  next  block  in  the 
chain.  Each  sequential  file  and  VLIR  record  on  the  disk  is  actually  a  chained  list 
of  blocks.  FollowChain  follows  these  track/sector  links,  adding  each  to  the  list 
at  TSTABLE  until  it  encounters  a  track  pointer  of  $(X),  which  terminates  the 
chain.  FollowChain  adds  this  last  track  pointer  ($00)  and  its  corresponding 
sector  pointer  (which  is  actually  an  index  to  the  last  valid  byte  in  the  block)  to  the 
track/sector  table  and  returns  to  the  caller. 

FollowChain  builds  a  standard  track/sector  table  compatible  with  routines  such 
as  WriteFile  and  FastDelFile. 

Apple  GEOS  has  no  FollowChain  equivalent  because  ProDOS  links  blocks 
together,  not  by  pointers  within  each  block,  but  by  a  list  of  blocks  in  an  index 
associated  with  each  sequential  file  and  VLIR  record  This  index  is  called  the 
index  block  and,  as  its  name  implies,  occupies  a  single  block  on  die  disk. 


LoadB 

LoadB 

LoadW 

jsr 

txa 

bne 


rlL,#START_TR 
rlH,#START_SC 
r3,#fUeTrScTab 
FollowChain 

HandleError 


;  start  track 

;  and  sector 

; buffer  for  table 

;  create  tr/sc  table 

;  set  status  flags 

;  branch  if  error 


See  also: 
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F^llowChain 


IFrameRectangle,  i  FrameRectangle  (Apple,  C64,  cm)  graphics] 


Function: 
Parameters: 


Uses: 

Returns: 
Destroys: 


Description: 


Note: 


128: 


Draw  a  rectangular  frame  (one-pixel  thickness). 
Normal: 

a        eight-bit  line  pattern. 
r3      XI  —  x-coordinate  of  upper-left  (word). 
r2L    Yl  —  y-coordinate  of  upper-left  (byte). 
r4      X2  —  x-coordinate  of  lower-right  (word). 
r2H    Y2  —  y-coordinateof  lower-right  (byte). 

where  (XI, Yl)  is  the  upper-left  corner  of  the  frame  and  (X2,Y2)  is  the  lower- 
right  corner. 

Inline: 

data  appears  immediately  after  the  jsr  i^FrameRectangle 

.byte   Yl  y-coordinate  of  upper-left 

.byte   Y2  y-coordinateof  lower-right, 

.word  XI  x-coordinate  of  upper-left 

.word  X2   x-coordinate  of  lower-right. 

.byte   PATTERN  eight-bit  line  pattern. 

dispBufferOn: 

bit  7  —  write  to  foreground  screen  if  set. 
bit  6  —  write  to  background  screen  if  set 

r2,  r3,  and  r4  unchanged. 

Commodore 

a,  X,  y,  r5-r9,  rll 

Apple 

a,x,  y,  rll 

FrameRectangle  draws  a  one-pixel  rectangular  frame  on  the  screen  as 
determined  by  the  coordinates  of  the  upper-left  and  lower-right  comers.  The 
horizontal  and  vertical  lines  which  comprise  the  frame  are  drawn  with  the 
specified  line  pattern. 

FrameRectangle  operates  by  calling  HorizontalLine  and  VerticalLine  with 
the  desired  line-pattern.  As  with  these  two  routines,  the  line  pattern  is  drawn  as  if 
aligned  on  an  eight-pixel  boundary.  The  values  of  the  comer  pixels  will  be 
determined  by  the  vertical  sides  because  they  are  drawn  after  the  hoi:izontal  sides. 

Because  all  GEOS  coordinates  are  inclusive,  framing  a  filled  rectangle  requires 
either  calling  FrameRectangle  after  calling  Rectangle  (and  thereby 
overwriting  the  perimeter  of  the  filled  area)  or  calling  FrameRectangle  with 
iXl'lJl-l)  and  (X2+1,Y2+1)  as  the  comer  points. 

Under  GEOS  128,  or'ing  DOUBLE  W  into  the  XI  andX2  parameters  will 
automatically  double  the  x-position  in  SD-column  mode.  Or'ing  in  ADD1_W  will 


FollowChain 


automatically  addl  to  a  doubled  x-position.  (Refer  to  "GEOS  128  X-position  and 
Bitmap  Doubling"  in  Chapter.@gr@  for  more  information.) 

Example: 

See  also:       Rectangle,  ImprintRectangle,  RecoverRectangle,  InvertRectangle. 


FYeeBlOCkjApple,  C64,  C128) 


mid-level  diskl 


Function: 
Parameters: 


Uses: 


Returns: 
Alters: 


Free  an  allocated  disk  block. 
Commodore: 

r6L  track  number  of  block  to  free  (byte). 
r6H      sector  number  of  block  to  free  (byte). 

Apple; 

r6        block  to  free  (word). 
curDrive 


Commodore: 
curDirHead 
dir2Headt 
dir3Headt 

Apple: 

curVBlknot 

VBMchangedt 

numVBMBIkst 


this  buffer  must  contain  the  current  directory  header. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use, 

X  error  ($00  =  no  error);  returns  BAD_B AM  if  block  already  free. 

r6L,  r6H  unchanged.  " 


Commodore: 
curDirHead 
dir2Headt 
dir3Headt 

Apple: 

curVBlknot 
VBMchangedt 


BAM  updated  to  reflect  newly  allocated  block. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


used  by  VBM  cacheing  routines. 

set  to  TRUE  by  VBM  cacheing  routines  to  indicate  cached 
VBM  block  has  changed  and  needs  to  be  flushed 


Destroys: 
Description: 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
a,  y,  r7,  rSH. 

FreeBIock  tries  to  free  (deallocate)  the  block  number  passed  in  r6.  If  the  block 
is  already  free,  then  FreeBIock  returns  a  BAD_BAM  error. 


C64  &  C128:  FreeBIock  was  not  added  to  the  Commodore  GEOS  jump  table  until  v  1.3,  but  it 
can  be  accessed  direcdy  under  GEOS  vl.2.  The  following  routine  will  check  the 
GEOS  version  number  and  act  correcdy  under  GEOS  vl.2  and  later. 

MyFreeBlock  —  allocate  specific  block  in  BAM 
with  any  GEM  device  driver. 


FrameRectangle 


•  *****************  *«*****4r*********  ********************* 


MyFreeBlock: 
Ida 
cmp 
bne 


Jsr 


bne 
Ida 
eor 
sta 
Idx 
inc 
Idx 
rts 


88$: 


10$: 


Idx 
rts 

jmp 


version 

#$12 

10$ 


FindBAMbit 


88$ 
r8h 

curOirHead, x 
curDirHead, x 
r7H 

curDirHead, x 
»0 


#BAD  BAM 


FreeBlock 


check  GEOS  version  number 
version  1.2? 

if  not,  go  through  jump  table 

r6L  «  track  # 
r6h  «  sector  # 

Get  mask  for  BAM  byte  in  r8H 
offset  to  track  in  r7h 
offset  into  bam  in  X 
masked  value  A 

if  1,  then  not  allocated,  give  error 

get  mask 

flip  BAM  bit  to  show  available 
one  more  free  block 
NO  ERROR 


;  BAM  ERROR 


;vl,3+:  go  thru  jump  tbl 


FreeBlock  does  not  automatically  write  out  the  BAM.  See  PutDirHead  for 
more  information  on  writing  out  the  BAM. 

Apple:  FreeBlock  does  not  automatically  flushctiie  VBM  cache.  See  PutVBM  for  more 

information  on  flushing  die  VBM  cache. 

Example: 

See  also:       FreeFile,  AllocateBlock. 


Dir 


FreeDir  (Apple) 


mid-level  disk! 


Function: 

Parameters: 

Uses: 


Free  the  chained  directory  blocks  associated  with  a  subdirectory.  Does  not  delete 
the  subdirectory's  directory  entry.  The  subdirectory  must  be  empty. 

r9        DIRENTRY  —  pointer  to  directory  entry  of  subdirectory  being  freed, 
usually  points  to  dirEntryBuf  (must  be  in  main  memory.)  (word). 


curDrive 
curVBlknot 
VBMchangedt 
numVBMBlkst 


used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


Returns: 
Alters: 


^used  internally  by  GEOS  disk  routines;  explications  generally  don't  use. 
X  error  ($00  =  no  error). 


diskBIkBuf 
curVBlknot 
VBMchangedt 


used  for  temporary  block  storage, 
used  by  VBM  cacheing  routines. 

set  to  FALSE  by  VBM  cacheing  routines  to  indicate  cached 
VBM  block  has  already  been  flushed 


Destroys: 
Description: 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
a,  y,  rl,  r4,  r6,  r7,  r8H. 

Given  a  valid  subdirectory  entry,  FreeDir  will  free  all  the  directory  blocks 
allocated  to  the  subdirectory.  The  subdirectory's  directory  entry,  however,  is  left 
intaa. 

« 

The  subdirectory  entry  is  a  standard  data  structure  returned  by  routines  such  as 
FIndFile,  GetlstDirEntry  and  GetNextDirEntry.  A  subdirectory  is  flagged 
by  a  PRO  DIR  in  the  GEOS  type  byte  in  the  directory  entry  (at 
OFF^FTYPt).  FreeDir  is  called  automatically  by  DeleteDir. 

FreeDir  will  not  free  the  blocks  of  subdirectory  that  has  files  in  it.  A 
DIR^NOT^EMPTY  error  will  be  returned.  (The  number  of  files  in  die 
subdSrcctoryls  stored  in  the  OFFB_FLCNT  word  of  the  directory's  header. 
This  maintains  this  value  by  calling  UpdateParent  when  files  are  added  or 
removed.) 

FreeDir  flushes  die  VBM  cache. 
C64  &  C128:  Commodore  GEOS  does  not  support  a  hierarchical  file  system. 
Example: 

See  also:       DeleteDir,  DeleteFile,  FreeFile,  FreeBIock. 
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FreeFile 


FreeFile  (Apple,  C64,  cns) 


mid-level  disk! 


Function: 
Parameters: 

Uses: 


Returns: 
Alters: 


Free  all  the  blocks  in  a  GEOS  file  (sequential  or  VLIR)  without  deleting  the 
direaory  entry.  The  GEOS  file  header  and  any  index  blocks  are  also  deleted. 

r9  DIRENTRY  —  pointer  to  directory  entry  of  file  being  freed,  usually 
points  to  dirEntryBuf  (Apple  GEOS:  must  be  in  main  memory.) 
(word). 

curDrive 

Cpmmodgrp; 
curType 

Apple; 

curVBIknot 
VBMchanged^ 
numVBMBlkst 


GEOS  64  vL3  and  later  for  detecting  REU  shadowing. 


used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines:  applications  generally  don't  use. 
X         error  ($(X)  =  no  error). 


diskBlkBuf 

CpmiTiodorp; 

curDirHead 

dir2Headt 

dirSHeadt 

fileHeader 


used  for  temporary  block  storage. 


BAM  updated  to  reflect  newly  fteed  blocks. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 

temporary  storage  of  the  index  table  when  deleting  a  VLIR 
file. 


Destroys: 


Applg; 

curVBIkno* 
VBMchangedt 


used  by  VBM  cacheing  routines. 

set  to  FALSE  by  VBM  cacheing  routines  to  indicate  cached 
VBM  block  has  already  been  flushed 


Description: 


^used  internally  by  GEOS  disk  routines;,  applications  generally  don't  use. 

Cpmmodorp; 
a,  y,  r0-r9. 

Apple: 

a,  y,  rl,  r2L,  r4,  r6,  r7,  r8H,  r9. 

Given  a  valid  directory  entry,  FreeFilfe  will  delete  (free)  all  blocks  assocatied 
with  the  file.  The  GEOS  file  header  and  any  index  blocks  associated  with  the  file 
are  also  be  freed.  The  directory  entry  on  the  disk,  however,  is  left  intact 

The  directory  entry  is  a  standard  GEOS  data  structure  returned  by  routines  such 
as  FindFile,  GetlstDirEntry  and  GetNxtDirEntry.  FreeFile  is  called 
automatically  by  DeleteFile. 
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C64  &  C128:  FreeFile  calls  GetDirHead  to  get  the  current  directory  header  and  BAM  into 
memory.  It  then  checks  at  OFF  GHDR^PTR  in  the  directory  entry  for  a  CEOS 
file  header  block,  which  it  then  ffees. 

If  the  file  is  a  sequential  file,  FreeFile  walks  the  chain  pointed  at  by  the 
OFF_DE_TR_SC  track/sector  pointer  in  the  directory  header  and  frtcs  all  the 
bloclcs  inlhe  chain.  FreeFile  then  calls  PutDirHead  to  write  out  the  new 
BAM. 

If  the  file  is  a  VLIR  file,  the  index  table  (the  block  pointed  to  by 
OFF JNDEX^PTR)  is  first  read  into  fileHeader  then  marked  as  free  in  the 
BAMT  FreeFife  then  goes  through  each  record.  If  the  record  has  data  in  it, 
FreeFile  walks  through  the  chain,  fieeing  all  the  blocks  in  the  record.  FreeFile 
finishes  by  calling  PutDirHead  to  write  out  the  new  BAM. 

When  using  GetlstDirEntry  and  GetNxtDirEntry,  do  not  pass  FreeFile  a 
pointer  into  diskBIkBuf.  Copy  the  full  directory  entry  (DIRENTRY^SIZE 
bytes)  from  diskBIkBuf  to  another  buffer  (such  as  dirEntryBuf)  and  pass 
FreeFile  the  pointer  to  that  buffer.  Otherwise  when  FreeFile  uses 
diskBIkBuf  it  will  corrupt  the  directory  entry. 

Because  FreeFile  deletes  a  block  at  a  time  as  it  follows  the  chains,  it  is  capable 
of  deleting  files  with  chains  larger  than  127  blocks,  which  is  the  standard  GEOS 
limit  imposed  by  the  size  of  TrScTable. 

Apple:  FreeFile  first  copies  the  entire  directory  entry  (ENTRY^SIZE  bytes)  from 

DIRENTRY  (in  main  memory)  to  an  internal  buffer  in  auxiliary  memory. 

If  tiie  file  is  a  VLIR  file,  then  FreeFile  reads  the  VLIR  index  block  (the  ProDOS 
*   master  index  block)  into  memory  and  frees  all  the  data  blocks  in  each  record.  The 
VLIR  index  block  and  all  the  individual  record  index  blocks  are  then  deleted. 
FreeFile  finishes  by  calling  PutVBM  to  flush  the  VBM  cache. 

If  the  file  is  a  sequential  file,  FreeFile  reads  the  sequential  index  block  into 
memory,  frees  all  assoiciated  data  blocks,.then  frees  the  index  block  itself. 
FreeFile  finishes  by  calling  PutVBM  to  flush  the  VBM  cache. 

FreeFile  cannot  free  a  subdirectory.  To  free  a  subdirectory,  use  FreeDir. 

Example: 

See  also:        DeleteFile,  FreeDir,  FreeBlock. 
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IFreezeProcess  (Apple,  C64,  ci287 


process] 


Function: 
Parameters: 

Returns: 

Destroys: 

Description: 


Note: 


Freeze  a  process's  countdown  timer  at  its  current  value. 

X       PROCESS  —  number  of  process  (0  -  n-1,  where  n  is  the  number  of 
processes  in  the  table)  (byte). 


X 

a 


unchanged. 


FreezeProcess  halts  a  process's  countdown  timer  so  that  it  is  no  longer 
decremented  every  vblank.  Because  a  frozen  timer  will  never  reach  zero,  the 
process  will  not  become  runable  except  through  a  call  to  EnableProcess.  When 
a  process  is  unfrozen  with  UnFreezeProcess,  its  timer  again  begins  counting 
from  the  point  where  it  was  frozen. 

If  a  process  is  already  frozen,  a  redundant  call  to  FreezeProcess  will  have  no 
effect. 


Example: 


See  also: 


UnfreezeProcess,  BlockProcess. 
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GetlstPirEntry  (Apple,  C64,  ci28) 


mid-level  disk! 


Function: 

Parameters: 
Uses: 


Loads  in  the  first  directory  block  of  the  current  directory  and  returns  a  pointer  to 
the  first  directory  entry  within  this  block. 


none. 

curDrive 

Commodore: 
curType 

Apple; 

curKBlkno 


GEOS  64  V  1.3  and  later  for  detecting  REU  shadowing. 


current  directory. 


Returns: 

Alters: 
Destroys: 
Description: 


X         error  ($00  =  no  error). 

r5        pointer  to  first  directory  entry  within  diskBlkBuf. 


diskBlkBuf 
a,  y,  rl,  r4. 


directory  block. 


GetlstDirEntry  reads  in  the  first  directory  block  of  the  current  directory  and 
returns  with  r5  pointing  to  the  first  directory  entry.  GetlstDirEntry  is  called  by 
routines  like  FindFTypes  and  FindFile. 

To  get  a  pointer  to  subsequent  directory  entiles,  call  GetNxtDirEntry. 

C64  &  C128:  Since  Conmiodore  GEOS  does  not  support  a  hierarchical  file  systeni,  the  "current 
directory"  is  actually  the  entire  disk. 

GetlstDirEntry  did  not  appear  in  the  jump  table  until  version  1.3.  An 
application  running  under  version  1.2  can  access  GetlstDirEntry  by  calling 
directly  into  the  Kemal.  The  following  subroutine  will  work  on  Commodore 
GEOS  vl. 2  and  later: 

•  ************* 


;  MyGetlstDirEntry  —  Call  instc^&d  of  GetlstDirEntry 
;        to  work  on  GEOS  vl.2  and  later 

r 

******************************************************* 

; EQUATE:  vl.2  entry  point  directly  into  Kernal.  Must 
;do  a  version  check  before  calling. 
o_GetlstDirEntry       -  $c9f7 


MyGetlstDirEntry: 

Ida  version 
cmp  #$13 
bge  10$ 

jmp  o_GetlstDirEntry 


10$: 


jmp 


GetlstDirEntry 


; exact  entry  point 

; check  version  number 

/branch  if  vl.3  or  later 
/direct  call 

;go  through  jump  table 


\ 
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Apple:  GetlstDirEntry  did  not  appear  in  the  jump  table  until  version  2.0,  release  3.  An 

application  running  under  an  earlier  version  can  add  GetlstDirEntry  mto  the 
jump  table  with  the  patch  provided  in  Appendix  @@. 


Example: 

See  also:        GetNxtDirEntry,  FindFTypes. 
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GetBlOCk  (Apple,  C64,  C128) 


low-level  disk! 


Function: 
Parameters: 


General  purpose  routine  to  get  a  block  from  current  disk. 

r4        BUFFER  —  address  of  buffer  to  place  block;  must  be  at  least 
BLOCKSIZE  bytes  (word). 

Commodore: 

rlL      TRACK  —  valid  track  number  (byte). 
rlH      SECrrOR  —  valid  sector  on  track  (byte). 

Applg; 

rl        BLOCK  —  ProDOS  block  number  (word). 


Uses: 


curDrive 

Commodore: 
curType 

Apple; 
RWbank 


currendy  active  disk  drive. 

GEOS  64  vl.3  and  later  for  detecting  REU  shadowing, 
bank  BUFFER  is  in  (MAIN  or  AUX). 


Returns: 

Destroys: 
Description: 


X  error  ($00  =  no  error), 

rl,  r4  "  unchanged 

a,  y. 

GetBlock  reads  a  block  from  the  disk  into  BUFFER.  GetBlock  is  useful  for 
implementing  disk  utility  programs  and  new  file  structures. 


C64  &  C128:  GetBlock  is  a  higher-level  version  of  ReadBlock.  It  calls  InitForlO, 
EnterTurbo,  ReadBlock,  and  DoneWithlO.  If  an  application  needs  to  read 
many  blocks  at  once,  ReadBlock  may  offer  a  faster  solution.  If  the  disk  is 
shadowed,  GetBlock  will  read  from  the  shadow  memory,  resulting  in  a  faster 
transfer. 


Apple: 

Example: 
See  also: 


The  Commodore  1581  driver  has  a  bug  that  causes  its  GetBlock  to  trash  rl  and 
r4. 

GetBlock  provides  the  lowest-level  block  access  to  a  ProDOS  compatible 
device.  It  uses  the  ProDOS  device  driver  READ  block  command  direcdy.  Apple 
GEOS,  for  this  reason,  does  not  have  a  ReadBlock  equivalent. 


PutBlock,  ReadBlock. 
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GetCharWidth  (Apple,  C64,  cus) 


text 


Function: 

Parameters: 

Uses: 

Returns: 

Destroys: 

Description: 


Example: 
See  also: 


Calculate  the  pixel  width  of  a  character  as  it  exists  in  the  font  (in  its  plaintext 
form).  Ignores  any  style  attributes. 

a       CHAR  —  character  code  of  character  (byte). 

curlndexTable 

a       character  width  in  pixels. 


GetCharWidth  calculates  the  width  of  the  character  before  any  style  attributes 
are  applied.  If  the  character  code  is  less. than  32,  $00  is  returned.  Any  other 
character  code  returns  the  pixel  width  as  calculated  from  the  font  data  structure. 

Because  GetCharWidth  does  not  account  for  style  attributes,  it  is  useful  for 
establishing  the  number  of  bits  a  character  occupies  in  the  font  data  structure. 


GetRealSize. 
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GetDimensions  (C64,  cns) 


printer  driver! 


Function: 

Parameters: 

Returns: 


Destroys: 
Description: 


Note: 


Get  printer  resolution, 
none. 

a  $00  =  printer  has  graphics  and  text  modes;  $ff  =  printer  only  has  text 

modes  (e.g.,  daisy  wheel  printers). 
X  PGWIDTH  —  page  width  in  cards:  number  of  8x8  cards  that  will  fit 

horizontally  on  a  page  (1-80,  standard  value  is  80  but  some  printers 

only  handle  60, 72,  or  75). 
y  PGHEIGHT  —  page  height  in  cards:  number  of  8x8  cards  that  will  fit 

vertically  on  a  page  (1-255,  usually  94). 

The  width  and  height  return  values  are  typically  based  on  an  85"  x  IV*  page 
with  a  025"  margin  on  all  sides,  leaving  an  8"  x  10  J"  usable  print  area. 

nothing. 

GetDimensions  returns  the  printable  page  size  in  cards.  At  each  call  to 
PrintBuffer,  the  printer  driver  will  expect  at  ltdiSXPGWIDTH  cards  of  graphic 
data  in  the  640-byte  print  buffer.  To  print  an  entire  page ,  the  application  will  need 
to  call  PrintBuffer  PGHEIGHT  times. 

Most  dot-matrix  printers  have  a  horizontal  resolution  of  80  dots-per-inch  and  an 
eight  inch  print  width.  Eight  inches  at  80  dpi  gives  640  addressable  dots  per 
printed  line,  and  640/8  equals  80  cards  per  line.  GEOS  assumes  an  80  dpi  output 
device. 

Drivers  for  printers  with  a  different  horizontal  resolution  will  usually  return  a 
PGWIDTH  value  that  reflects  some  even  multiple  of  the  dpi.  For  example,  a 
lower  resolution  72  dpi  printer  can  only  fit  72*8  =  560  dots  per  line,  and  560 
dots  reduces  to  72  cards.  PGWIDTH  in  this  case  would  come  back  as  72. 

A  300  dpi  laser  printer,  however,  can  accomodate  2,400  dots  on  an  eight  inch 
line.  To  scale  80  dpi  data  to  300  dpi,  each  pixel  is  expanded  to  four  times  its 
normal  width.  If  the  printer  driver  tried  to  print  the  full  640  possible  dots  at  this 
expanded  width,  it  would  lose  the  last  160  dots  because  the  printer  itself  can  only 
handle  2,400  dots  in  an  eight  inch  space  and  640*4  =  2,560.  To  alleviate  this 
problem  he  printer  driver  truncates  the  width  at  the  card  boundary  nearest  to 
2,400  dots,  which  happens  to  be  75  cards.  Hence,  in  this  case,  PGWIDTH 
would  come  back  as  75. 

The  size,  PGHEIGHT,  reflects  the  number  of  card  rows  to  send  through 
PrintBuffer  to  fill  a  full-page.  If  more  rows  are  sent,  then  (depending  on  the 
printer  and  the  driver)  the  printing  will  usually  continue  onto  the  next  page 
(pnniing  over  the  perforation  on  z-fold  paper).  The  application  will  usually  keep 
an  mtemal  card-row  counter  and  call  StopPrint  to  advance  to  the  next  page. 

It  is  not  necessary  to  call  GetDimensions  when  printing  ASCII  text. 
Commodore  GEOS  printer  drivers  always  assume  80  columns  by  66  lines. 
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Apple:  This  routine  is  not  supported  under  Apple  GEOS.  Apple  GEOS  offers  a  more 

sophisticated  printer  driver  scheme.  Refer  to  GetMode  for  more  information. 

See  also:        StartPrint,  StartASCII. 
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GetPirHead  (Apple,  C64,  cus) 


mid-level  disk 


Function:  Read  directory  header  from  disk.  Commodore  GEOS  also  reads  in  the  BAM. 
Parameters:  none. 


Uses: 


curDrive 

Commodore: 
curType 

Applg; 

curKBlkno 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing. 


current  directory  key  block. 


Returns: 


Alters: 


X  error  ($00  =  no  eiror). 

Commodore: 

r4        pointer  to  curDirHead. 


curDirHead 

Commodore: 

dir2Headt 

dir3Headt 


contains  directory  header  (39  bytes  on  Apple). 


(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


Destroys: 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 

Comm9<j(3rp; 
a,  y,  rl. 


Description: 


Appig; 

a,  y,  rl.  r4. 

GetDirHead  reads  the  directory  header  into  the  buffer  at  curDirHead.  Because 
of  differences  in  the  Commodore  and  Apple  file  systems,  this  can  mean  different 
things.  Commodore  GEOS  places  the  full  directory  header  block  (256  bytes)  into 
curDirHead.  This  block  also  includes  the  BAM  (block  allocation  map)  for  the 
entire  disk.  Apple  GEOS.  on  the  other  hand,  only  places  the  39-byte  ProDOS 
directory  header  for  the  current  directory  into  curDirHead. 

C64  &  C128:  GEOS  disks,  like  the  standard  Ctommodore  disks  upon  which  they  are  based, 
have  one  directory  header.  The  directory  header  occupies  one  full  block  on  the 
disk.  The  Commodore  directory  header  contains  information  about  the  disk,  such 
as  the  location  of  the  directory  blocks,  the  disk  name,  and  the  GEOS  version 
string  (if  a  GEOS  disk).  The  Commodore  directory  header  also  contains  the  disk 
BAM,  which  flags  particular  sectors  as  used  or  unused 

GetDirHead  calls  GetBlock  to  read  in  the  directory  header  block  into  the 
buffer  at  curDirHead.  The  directory  header  block  contains  the  directory  header 
and  the  disk  BAM  (block  allocation  map).  Typically,  applications  don't  call 
GetDirHead  because  the  most  up-to-date  directory  header  is  almost  always  in 
memory  (at  curDirHead),  OpenDisk  calls  GetDirHead  to  get  it  there 
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initially.  Other  GEOS  routines  update  it  in  memory,  some  calling  PutDlrHead  to 
bring  the  disk  version  up  to  date. 

Because  Commodore  disks  store  the  BAM  information  in  the  directory  header  it  is 
important  that  the  BAM  in  memory  not  get  overwritten  by  an  outdated  BAM  on 
the  disk.  An  application  that  manipulates  the  BAM  in  memory  (or  calls  GEOS 
routines  that  do  so),  must  be  careful  to  write  the  BAM  back  out  (with 
PutDirHead)  before  calling  any  other  routine  that  might  overwrite  the  copy  in 
memory.  GetDirHead  is  called  by  routines  such  as  OpenDisk, 
SetGEOSDisk,  and  GpenRecordFile,  etc. 

Apple:  Apple  GEOS  disks,  like  tiie  ProDOS  disks  upon  which  they  are  based,  have  a 

directory  header  for  each  directory.  The  header  for  the  root  directory  is  called  a 
volume  directory  header  and  the  header  for  a  subdirectory  is  called  a  subdirectory 
header.  These  directory  headers  arc  39-byte  structures  defined  by  ProDOS.  They 
contain  such  information  as  the  directory  name,  the  date  stamp,  and  read/write 
access  flags.  The  directory  header  does  not  contain  the  VBM  (volume  bit  map,  the 
Apple  equivalent  of  a  BAM). 

GetDirHead  reads  in  the  key  block  of  the  current  directory  (pointed  at  by 
curKBIkno)  and  copies  the  39-byte  directory  header  information  to 
curDirHead. 


Since  Apple  GEOS  does  not  store  the  allocation  map  (VBM)  in  die  directory 
header  Uke  Commodore  GEOS,  it  not  necessary  to  be  as  careful  about  rereading 
the  directory  header.  For  more  information  on  reading  the  Apple  VBM,  refer  to 
GetVBM. 

Example: 

See  also:       PutDirHead,  GetVBM,  PutVBM. 
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GetFHdrlnfo  (Apple,  C64,  cns) 


mid-level  disk 


Function: 
Parameters: 

Uses: 
Returns: 


Alters: 


Destroys: 
Description: 


Loads  the  GEOS  file  header  for  a  particular  directory  entry. 

r9        DIRENTRY  —  pointer  to  directory  entry  of  file,  usually  points  to 
dirEntryBuf  (Apple  GEOS:  must  be  in  main  memory)  (word). 

curDrive 


Commodore: 
curType 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing. 


X         error  ($00  =  no  error). 

r7        load  address  copied  from  the  O^GHST^ADDR  word  of  the  GEOS 
file  header. 

Commodore: 


rl 


Applg; 
rl 


track/sector  copied  from  bytes  +1  and  +2  of  the  directory  entry 
(DIRENTRY),  This  is  the  track/sector  of  the  first  data  block  of  a 
sequential  file  (OFF  DE  TR  SC)  or  the  index  table  block  of  a  VLIR 
file  (OFF  INDEX  TPTff).  " 


block  number  of  sequential-file  index  block  or  VLIR  master  index  block 
as  copied  from  the  OFF^FINDX  byte  of  the  directory  entry. 


fileHeader 

CQmnyyjqrsi 
fileTrScTab 


a,  y,  r4. 


contains  256-byte  GEOS  file  header. 


track/sector  of  header  added  to  first  ♦wo  bytes  of  this  table;  a 
subsequent  call  to  ReadFile  or  similar  routine  will  augment 
this  table  beginning  with  the  third  byte  (fileTrScTab+2)  so 
as  not  to  disrupt  this  value. 


Given  a  valid  directory  entry,  GetFHdrlnfo  will  load  the  GEOS  file  header  into 
the  buffer  at  fileHeader. 

The  directory  entry  is  a  standard  GEOS  data  structure  returned  by  routines  such 
as  FindFile,  GetlstDirEntry  and  GetNextDirEntry.  GetFHdrlnfo  is 
called  by  routines  such  as  LdFile  just  prior  to  calling  ReadFile  (to  load  in  a 
sequential  file  or  record  zero  of  a  VLIR). 

GetFHdrlnfo  gets  the  block  number  (Commodore  track/sector)  of  the  GEOS 
file  header  by  looking  at  the  OFF_GHDR_PTR  word  in  the  directory  entry. 


Example: 
See  also: 
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GetFile  (Apple,  C64,  C128) 


high-level  disk 


Function:       General-purpose  file  routine  that  can  load  an  application,  desk  accessory,  or  data 
file. 


Parameters:  r6 


FILENAME  —  pointer  to  null-terminated  filename  (word). 


Uses: 


When  loading  an  application: 
rOL  LOAD^OFT: 

bit  0:  0  load  at  address  specified  in  file  header,  application  will  be 
started  autmatically 
1  load  at  address  in  r7;  application  will  not  be  staned 
automatically, 
bit?:  0  not  passing  a  data  file. 

1  r2  and  r3  contain  pointers  to  disk  and  data  file  names, 
bit  6:  0  not  printing  data  file. 

printing  data  file;  application  should  print  file  and  exit 
r7        LOAD_ADDR  —  optional  load  address,  only  used  if  bit  0  of 

LOAD  JOPT  is  set  (word). 
r2        DATA^DISK— only  valid  if  bit  7  or  bit  6  of  LOAD  jOPT  is  set:  pointer 
to  name  of  the  disk  that  contains  the  data  file,  usually  a  pointer  to  one  of 
the  DrxCurDkNm  buffers  (word). 
r3        DATA.FILE  —  only  valid  if  bit  7  or  bit  6  of  LOAD  jOPT  is  set:  pointer 
to  name  of  the  data  file  (word). 

When  iQ^ding  a  de?k  accessory; 

rlOL     REGVR^OPTS  —  no  longer  used;  set  to  $00  (see  below  for  explanation 
(byte). 

curDrive 


CptpmodoTp; 

curType 

Apple; 
RWbank 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing. 


destination  bank  (MAIN  or  AUX);  always  set  to  MAIN 
when  loading  an  application  or  desk  accessory. 


Returns:       When  loa(iing  ap  applicatfon; 

only  returns  if  alternate  load  address  or  disk  error. 
X  error  ($(X)  =  no  error). 

rO,  r2,  r3,  and  r7  unchanged. 

When  loading  a  desk  accessory: 

returns  when  desk  accessory  exits  with  a  call  to  RstrAppl. 
X         error  ($(X)  =  no  error). 

When  loading  a  data  file: 

X         error  ($(X)  =  no  em)r). 

Passes:  When  loading  an  application! 

warmstarts  GEOS  and  passes  the  following  to  the  application: 
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rO        as  originally  passed  to  GetFile. 
r2        as  originally  passed  to  GetFile  (use  dataDiskName). 
r3        as  originally  passed  to  GetFile.(use  dataFileName). 
dataDiskName     contains  name  of  data  disk  if  bit  7  of  rO  is  set 
dataFileName      contains  name  of  data  file  if  bit  6  of  rO  is  set 

When  loading  a  desk  accessory: 
warmstarts  GEOS  and  passes  the  following: 
rIOL     as  originally  passed  to  GetFile. 

When  loading  a  data  file: 
not  applicable. 

Alters:  When  loading  an  application: 

GEOS  brought  to  a  warmstart  state. 

Destroys:       a,  x,  y,  rO-rlO  (only  applies  to  loading  a  data  file). 

Description:  GetFile  is  the  preferred  method  of  loading  most  GEOS  files,  whether  a  data  file, 
application,  or  desk  accessory.  (The  only  exception  to  this  is  a  VLIR  file,  which 
is  better  handled  with  the  VLIR  routines  such  as  OpenRecordFile  and 
ReadRecord).  Most  applications  will  use  GetFile  to  load  and  execute  desk 
accessories  when  the  user  clicks  on  an  item  in  the  geos  menu.  Some  applications 
will  use  GetFile  to  load  other  applications.  The  GEOS  deskTop,  in  fact,  is  just 
another  application  like  any  odier.  Depending  on  the  user's  choice  of  actions  — 
open  an  application,  open  an  application's  data  file,  print  an  applications'  data  file 
—  die  deskTop  sets  LOADjOPT,  DATA^DISK,  DATAJFILE  appropriately  and 
calls  GetFile. 


GetFile  first  calls.FindFile  to  locate  die  file  at  FILENAME,  then  checks  the 
GEOS  file  type  in  the  directory  entry.  If  the  file  is  type  DESK  ACC,  then 
GetFile  calls  LdDeskAcc.  If  die  file  is  type  APPLICATIDN  or  type 
AUTO^EXEC,  GetFile  calls  LdApplic.  All  odier  file  types  are  loaded  widi 
the  generic  LdFile. 

The  following  GEOS  constants  can  be  used  to  set  the  LOADjOPT  parameter 
when  loading  an  application: 


ST_LD_AT_.ADDR 

Load  at  address:  load  application  at  the  address  passed  in 
r7  as  opposed  to  the  address  in  the  file  header. 

ST^LD^DATA 

Load  data  file:  aj^lication  is  being  passed  the  name  of  a 
data  file  to  load. 

ST^PR^DATA 

Print  data  file:  aiqplication  is  being  passed  the  name  of  a 
data  file  to  print 

Note:  The  RECVRjOPTS  flag  used  when  loading  desk  accessories  originally  carried 

die  following  significance: 

bit  7:   1    force  desk  accessory  to  save  foreground  screen  area  and  restore  it  on  return  to 
application. 

0    not  necessary  for  desk  accessory  to  save  foreground. 
Commodore  only; 

bit  6:   1    force  desk  accessory  to  save  color  memory  and  restore  it  on  return  to 
application. 
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0    not  necess^  for  desk  accessory  to  save  color  memory. 

However,  it  was  found  that  the  extra  code  necessary  to  make  desk  accessories 
save  the  foreground  screen  and  color  memory  provided  no  real  benefit  because 
this  context  save  can  just  as  easily  be  accomplished  from  within  the  application 
itself.  The  RECVRjOPTS  flag  is  set  to  $00  by  all  Berkeley  Softworks 
applications,  and  desk  accessories  can  safely  assume  that  this  will  always  be  the 
case.  (In  fact,  future  versions  of  GEOS  may  force  rlOH  to  $00  before  calling 
desk  accessories  just  to  enforce  this  standard! ) 

The  application  should  always  set  rlOH  to  $00  and  bear  the  burden  of  saving  and 
restoring  the  foreground  screen  and  the  color  memory.  (Color  memory  only 
applicable  to  GEOS  64  and  GEOS  128  in  40-column  mode.) 

Apple:  Applications  and  desk  accessories  arc  designed  to  load  into  main  memory.  Ensure 

that  RWbank  contains  MAIN  before  calling  GetFile  to  load  anything  but  a  data 
file. 

Example: 

See  also:        LdFile,  LdDeskAcc,  LdApplic. 
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GetFreeDirBlk  (Apple,  C64,  ci28) 


mid-level  disk 


Function: 
Parameters: 

Uses: 


Search  the  current  directory  for  an  empty,  slot  for  a  new  directory  entry.  Allocates 
another  directory  block  if  necessary. 

rlOL  DIRPAGE  —  directory  page  to  begin  searching  for  free  slot;  each 
directory  page  holds  eight  files  and  corresponds  to  one  notepad  page  on 
the  GEOS  deskTop.  The  first  page  is  page  one. 

curDrive 

COniniQ<jorg; 

curType  GEOS  64  vl.3  and  later:  for  detecting  REU  shadowing. 

curDirHead        this  buffer  must  contain  the  current  directory  header. 
dir2Headt  (BAM  for  1571  and  1581  drives  only) 

dirSHeadt  (BAM  for  1581  drive  only) 

interleave^  desired  physical  sector  interleave  (usually  8);.  applications 

need  not  set  this  explicitly  —  will  be  set  automatically  by 
internal  GEOS  routines.  Only  used  when  new  directory 
block  is  allocated 


Returns: 


Alters: 


Apple: 

curKBIkno 
curVBlknot 
VBMchangedt 
numVBMBlkst 


current  directory, 
used  by  \'BM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 

X  error  ($00  =  no  error). 

rlOL     page  number  of  empty  directory  slot. 

rl        block  (Commodore  track/sector)  number  of  directory  block  in 
diskBlkBuf. 

Commodore: 

y         index  to  empty  directory  slot  in  diskBlkBuf. 


Apple; 
r3 

rlOH 


pointer  to  empty  directory  slot  in  diskBlkBuf.  This  is  an  absolute 
address,  not  an  index  into  diskBlkBuf. 

unused  directory  entry  within  block  in  diskBlkBuf.  There  are  13 
directory  entries  per  ProDOS  block,  numbered  1-13. 


Commodore: 
curDirHead 
dirlHeadt 
dir3Headt 

Apple; 

curVBlknot 
VBMchangedt 


BAM  updated  to  reflect  newly  allocated  block! 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


used  by  VBM  cacheing  routines. 

set  to  TRUE  by  VBM  cacheing  routines  to  indicate  cached 
VBM  block  has  changed  and  needs  to  be  flushed 
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^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 

Destroys:  CpiprTKyjorg: 

a,  rO,  r3,  rS,  r7-r8. 

Apple: 

a»    r4-r5,  r7-r8. 

Description:  GetFreeDirBlk  searches  the  current  directory  looking  for  an  empty  slot  for  a 
new  directpry  entry.  A  single  directory  page  has  eight  directory  slots,  and  these 
eight  slots  correspond  to  the  eight  possible  files  that  can  be  displayed  on  a  single 
GEOS  deskTop  notepad  page. 

GetFreeDirBlk  starts  searching  for  an  empty  slot  beginning  with  page  number 
DIRPAGE.  If  GetFreeDirBlk  reaches  the  last  directory  entry  without  finding 
an  empty  slot,  it  will  try  to  allocate  a  new  directory  block.  If  DIRPAGE  doesn't 
yet  exist,  empty  pages  are  added  to  the  directory  structure  until  the  requested  page 
is  reached. 

$01  will  most  often  be  passed  as  the  DIRPAGE  starting  page  number,  so  that  all 
possible  directory  slots  will  be  searched,  starting  with  the  fiirst  page.  If  higher 
numbers  are  used,  GetFreeDirBlk  won't  find  empty  directory  slots  on  lower 
pages  and  extra  directory  blocks  may  be  allocated  needlessly. 

GetFreeDirBlk  is  called  by  SetGDirEntry  before  writing  out  the  directory 
entry  for  a  new  GEOS  file. 

C64  &  C128:  Since  Conimodore  GEOS  does  not  support  a  hierarchical  file  systeni,  the  "current 
directory"  is  actually  the  entire  disk.  A  dkectory  page  corresponds  exacdy  to  a 
single  sector  on  the  directory  track.  There  is  a  maximum  of  18  directory  sectors 
(pages)  on  a  Commodore  disk.  If  this  18th  page  is  exceeded,  GetFreeDirBlk 
will  return  a  FULL^DIRECTORY  error. 

GetFreeDirBlk  allocates  blocks  by  calling  SetNextFree  to  allocate  sectors  on 
the  directory  track.  SetNextFree  wUl  specid-case  the  directory  track  allocations. 
Refer  to  SetNextFree  for  more  information. 

GetFreeDirBlk  does  not  automatically  write  out  the  BAM.  See  PutDirHead 
for  more  information  on  writing  out  the  BAM. 

Apple:  ProDOS  directory  blocks  (and  therefore  GEOS  directory  blocks)  contain  13 

directory  slots.  This  requires  Apple  GEOS  to  map  GEOS's  eight-entry  directory 
pages  to  tiiese  13-entry  blocks,  sometimes  forcing  a  page  to  straddle  a  block 
boundary.  Most  applications  need  not  worry  about  this  straddling  as  it  is  made 
transparent  by  GEOS  routines  such  as  FindFile. 

If  an  empty  directory  slot  is  not  found  and  the  end  of  the  last  block  of  the  current 
directory  is  reached,  GetFreeDirBlk  calls  SetNextFree  to  allocate  a  new 
directory  block.  The  number  of  blocks  in  a  ProEKDS  directory  is  limited  only  by 
space.  liF  there  is  no  more  space  on  the  disk  for  another  directory  block,  and 
INSUFFICIENT^SPACE  error  is  returned. 
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GetFreeDirBIk  does  not  automatically  flush  the  VBM  cache.  See  PutVBM 
more  information  on  flushing  the  cache. 

Example: 

See  also:        AIlocateBlock,  FreeBIock,  BIkAIloc. 


114 


GetLdVars 


GetLdVars  (Apple) 


mid-level  disk 


Function:       Transfers  the  internal  "Ld"  variables  (those  used  by  LdAppl,  LdDeskAcc,  and 
LdFile)  to  GEOS  pseudoregisters. 

Parameters:  none. 


Returns: 


rOL 


Destroys: 
Description: 


r7 
r2 


r3 

rlOL 


a. 


LOAD.OPT: 

bitO:  0  load  at  address  specified  in  file  header;  application  will  be 
started  autmatically 
1  load  at  address  in  r7;  application  will  not  be  started 
automatically, 
bit?:  0  not  passing  a  data  file. 

1  r2  and  r3  contain  pointers  to  disk  and  data  file  names, 
bit  6:  0  not  ininting  data  file. 

printing  data  file;  application  should  print  ^e  and  exit 
LOAD_ADDR  —  optional  load  address,  only  used  if  bit  0  of 
WADJDPT  is  set  (word). 

DATA^DISK  —  only  valid  if  bit  7  or  bit  6  of  LOAD  JOPT  is  set:  pointer 
to  name  of  the  disk  that  contains  the  data  file,  usually  a  pointer  to  one  of 
the  DrjcCurDkNm  buffers  (word). 

DATA^FILE  —  only  valid  if  bit  7  or  bit  6  of  LOAD  jOPT  is  set:  pointer 
to  name  of  the  data  file  (word). 
RECVR.OPTS  (byte). 


GetLdVars  transfers  the  internal  load  varaibles  to  GEOS  pseudoregisters. 
GetFile,  LdApplic,  LdDeskAcc,  and  LdFile  call  GetLdVars  as  necessary. 
Most  applications  will  not  need  to  call  it  direcdy. 


See  also: 


SetLdVars. 
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GetMode  (Apple) 


printer  driver 


Function:  Get  printer  resolution  and  setable  attributes. 
Parameters:  none. 


Returns: 


Destroys: 
Description: 


a  ASCnWIDTH  —  page  width  for  ASCII  printing  (characters  per  line), 

assumes  10  cpi  pitch  (byte). 
X  PGWIDTH  —  page  width  in  cards:  number  of  8x8  cards  that  will  fit 

horizontally  on  a  page  (1-80,  standard  value  is  80  but  some  printers 

only  handle  60,  72,  or  75)  (byte).  If  $00,  then  this  is  an  older  driver: 

assume  80  cards. 

y  PGHEIGHT  —  page  height  in  cards:  number  of  8x8  cards  that  will  fit 

vertically  on  a  page  (1-255,  usually  94)  (byte). 
rO-r2L  MODE  —  flags  for  possible  printer  modes  and  capabilities  (five  bytes). 

The  width  and  height  values  are  typically  based  on  an  85" xU"  page  with  a 
025"  margin  on  all  sides,  leaving  an  8"  x  105"  usable  print  area. 

assume  r2H-r4. 

GetMode  returns  information  concerning  the  resolution  and  capabilites  of  the 

nnntpr 


currently  installed  printer. 


Graphic  Printing: 

At  each  call  to  PrintBuffer,  the  printer  driver  will  expect  at  leastFGW^/Dr// 
cards  of  linear  bitmap  data  in  the  640-byte  print  buffer.  To  print  an  entire  page  , 
the  application  will  need  to  call  PrintBuffer  PGHEIGHT  times. 

Most  dot-matrix  printers  have  a  horizontal  resolution  of  80  dots-per-inch  and  an 
eight  inch  print  width.  Eight  inches  at  80  dpi  gives  640  addressable  dots  per 
printed  line.  Since  GEOS  printer  output  is  designed  to  map  dirccdy  from  screen 
graphics,  it  is  sometimes  useful  to  think  of  it  in  terms  of  cards  (8x8  pixel  blocks). 
There  80  (640/8)  80  cards  per  printable  line.  GEOS  always  assumes  an  80  dpi 
output  device. 

Drivers  for  printers  with  a  different  horizontal  resolution  will  usually  return  a 
PGWIDTH  value  that  reflects  some  even  multiple  of  the  dpi.  For  example,  a 
lower  resolution  72  dpi  printer  can  only  fit  72*8  =  560  dots  per  line,  and  560 
dots  reduces  to  72  cards.  PGWIDTH  in  this  case  would  come  back  as  72.  The 
printer  driver  will  only  ouput  the  first  72  cards  (560  dots)  on  each  line. 

A  300  dpi  laser  printer,  however,  can  accomodate  2,400  dots  on  an  eight  inch 
line.  To  scale  80  dpi  data  to  300  dpi,  each  pixel  is  expanded  to  four  times  its 
normal  width.  But  640*4  =  2,560,  which  is  160  dots  more  than  the  printer  can 
handle.  If  the  printer  driver  tried  to  print  the  full  640  possible  dots  at  this 
expanded  width,  it  would  lose  the  last  160  dots.  The  printer  driver  truncates  the 
width  at  the  card  boundary  nearest  to  2,400  dots,  which  happens  to  be  75  cards 
(75*8*4  =  2400).  Hence,  in  this  case,  PGWIDTH  would  come  back  as  75. 

The  size,  PGHEIGHT,  reflects  the  number  of  card  rows  to  send  through 
PrintBuffer  to  fill  a  full-page.  If  more  rows  are  sent,  then  (depending  on  Ae 
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printer  and  the  driver)  the  printing  will  usually  continue  onto  the  next  page 
(printing  over  the  perforation  on  z-fold  paper).  The  application  will  usually  keep 
an  internal  card-row  counter  and  call  StopPrint  to  advance  to  the  next  page. 

ASCII  Printing; 

The  printer  is  capable  of  printing  ASCUWIDTH  characters  per  line  and  66  lines 
per  page. 

The  MODE  W^ue^: 

GetMode  returns  a  number  of  flags  in  rO-r2L.  These  flags  determine  whether  a 
specific  feature  is  offered  by  the  current  printer  and  its  printer  driver.  These  bits 
correspond  to  features  that  may  be  set  with  SetMode: 

rOL:    (matches  currentMode  text  variable) 


bit 

description 

b7 

^underline. 

b6 

b5 

reverse. 

b4 

^italic. 

b3 

outline. 

b2 

^superscript 

bl 

^subscript 

bO 

reserved  for  future  use. 

(text  density) 

bit  description 

b7 

+picatype(10  cpi). 

b6 

^elite  type  (12  cpi). 

b5 

^condensed  type  (16  cpi). 

b4 

"  ^proportional  type. 

b3 

^double  height 

b2 

^half-height 

bl 

^eighi  lines  per  inch  vertical  density. 

bO 

^six  lines  per  inch  vertical  density. 

(miscellaneous  features) 
bit  description 

b7 

print  red  or  magenta.  . 

b6 

print  yellow. 

b5 

print  blue  or  cyan. 

b4 

^expanded  (double-width)  type. 

b3 

*NLO  (near  letter  quality)  type. 

b2 

CR  always  linefeeds,  preventing  manual  overstrike  by  application 

bl 

reserved  for  future  use. 

bO 

reserved  for  future  use. 
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rlH:    (internal  font  availability) 


bit 

description 

b7 

font  7. 

b6 

font  6. 

b5 

font  5. 

b4 

font  4, 

b3 

font  3. 

b2 

font  2  (Roman?). 

bl 

font  1  (Helvetica?). 

bO 

font  0  (Courier?). 

(horizontal  graphics  density) 
bit  description 

b7 

60  dpi. 

b6 

^SOdpi. 

b5 

90  dpi. 

b4 

120  dpi. 

b3 

180  dpi. 

b2 

300  dpi. 

bl 

360  dpi. 

bO 

reserved  for  future  use. 

^This  feature  implemented  in  most  Berkeley  Softworks  printer  drivers. 
C64  &  C128:  Refer  to  GetDimensions. 
See  also:  SetMode. 
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GetNextChar  (Apple,  C64,  cns) 


text/keyboard  I 


Function: 
Parameters: 
Returns: 
Alters: 

Destroys: 


Retrieve  the  next  character  firom  the  keyboard  queue, 
none. 

a       keyboard  character  code  of  characer  or  NULL  if  no  characters  available. 

pressFIag  if  the  call  to  GetNextChar  removes  the  last  character  from 

the  queue,  then  the  KEYPRESS^BIT  is  cleared. 


Description:  GetNextChar  checks  the  keyboard  queue  for  a  pending  keypress  and  returns  a 
non-zero  value  if  one  is  available.  This  allows  more  tihian  one  character  to  be 
processed  without  returning  to  MainLoop. 


Example: 
See  also: 


GetString. 
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GetNxtPirEntry  (Apple,  C64,  cm) 


mid-level  disk 


Function: 
Parameters: 

Uses: 


Given  a  pointer  to  a  directory  entry  returned  by  GetlstDirEntry  or 
GetNxtDirEntry,  returns  a  pointer  to  the  next  directory  entry.. 

rS  CURDIRENTRY  —  pointer  to  current  directory  entry  as  returned  from 
GetlstDirEntry  or  GetNxtDirEntry;  will  always  be  a  pointer  into 
diskBlkBuf  (word). 


curDrive 
diskBlkBuf 


Commodore: 
curType 


must  be  unaltered  from  previous  call  to  GetlstDirEntry  or 
GetNxtDirEntry. 


GEOS  64  vl.3  and  later,  for  detecting  REU  shadowing. 


Returns: 


Alters: 
Destroys: 


X  error  ($00  =  no  error). 

rS  pointer  to  next  directory  entry  within  diskBlkBuf. 
Commodore: 

y  non-zero  if  end  of  directory  reached 


directory  block. 


diskBlkBuf 

Ctommodore: 
a,  rl,  r4. 

Commodore: 
a,  y,  rl,  r4. 

Description:  GetNxtDirEntry  increments  rS  to  point  to  the  next  directory  entry  in 
diskBlkBuf.  If  diskBlkBuf  is  exceeded,  the  next  directory  block  is  read  in 
and  r5  is  returned  with  an  index  into  this  new  block.  Before  calling 
GetNxtDirEntry  for  the  first  time,  call  GetlstDirEntry. 

C64  &  C128:  GetNxtDirEntry  did  not  appear  in  the  jump  table  until  version  1.3.  An 
application  running  under  version  1.2  can  access  GetNxtDirEntry  by  calling 
directiy  into  the  Kemal.  The  following  subroutine  will  work  on  Commodore 
GEOS  V  1.2  and  later: 


MyGetNxtDirEntry  —  Use  instead  of  GetNxtDirEntry 
to  work  on  GEOS  vl.2  and  later 


/EQUATE:  vl.2  entry  point  directly  into  Kernal.  Must 
;do  a  version  check  before  calling, 
©^GetNxtDirEntry       =  $calO  ; exact  entry  point 


MyGetNxtDirEntry: 

Ida  version 
cmp  #$13 
bge  10 


; check  version  number 
/branch  if  vl.3  or  later 


120 


GetNxtDirEntry 


jmp  o_GetNxtDirEntry       /direct  call 

10$: 

jmp  GetNxtDirEntry  ;thru  jump  table 

Apple:  GetNxtDirEntry  did  not  appear  in  the  jump  table  until  version  2.0,  release  3. 

An  application  running  under  an  earlier  version  can  add  GetNxtDirEntry  into 
the  jump  table  with  the  patch  provided  in  Appendix  @@. 

Example: 

See  also:        GetlstDirEntry,  FindFTypes. 
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GetOffPageTrSc   (C64,  C128)  mid-level  diski 


Function:       Get  track  and  sector  of  off-page  directory. 


Parameters:  none. 

Uses:  curDrive 

curType  GEOS  64  vl.3  and  later:  for  detecting  REU  shadowing. 


Returns:         x  error  ($00  =  no  error). 

y         $ff  if  the  disk  is  not  a  GEOS  disk  and  therefore  has  no  off-page 

directory  block,  otherwise  $00. 
rlL      track  of  off-page  directory, 
r  1 H      sector  of  of f-page  directory. 
r4        pointer  to  curDirHead. 


Alters: 


curDirHead 
dir2Headt 
dir3Headt 
isGEOS 


contains  directory  header. 

(BAM  for  1571  and  1581  drives  only) 

(BAM  for  1581  drive  only) 

set  to  TRUE  if  disk  is  a  GEOS  disk,  otherwise  set  to 
FALSE. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 


Destroys:  Commodore: 
a,  y,  rS. 

Description:  Commodore  GEOS  disks  have  an  extra  directory  block  somewhere  on  the  disk 
called  the  off-page  directory.  The  GEOS  deskTop  uses  the  off-page  directory 
block  to  keep  track  of  file  icons  that  have  been  dragged  off  of  the  notepad  and 
onto  the  border  area  of  the  deskTop.  The  off-page  directory  holds  up  to  eight 
directory  entries. 

GetOffPageTrSc  reads  the  directory  header  into  the  buffer  at  curDirHead  and 
calls  ChkDkGEOS  to  ensure  that  the  disk  is  a  GEOS  disk.  If  the  disk  is  not  a 
GEOS  disk,  it  returns  with  $ff  in  the  y  register.  Otherwise,  GetOffPageTrSc 
copies  the  off-page  track/sector  from  the  OFF_OP_TR_SC  word  in  the 
directory  header  to  rl  and  returns  $00  in  y.  -     -  - 

Apple:  Apple  GEOS  does  not  use  an  off-page  directory  block.  The  Apple  GEOS 

deskTop  manages  files  that  are  draggai  onto  the  border  area  entirely  in  software. 

Example: 

;  Put  off-page  block  into  DiskBlkBuf 


jsr  GetOffPageTrSc  ;get  of f-page  directory  block 

txa  ; check  for  error 

bne  99$  ; 

tya  ; check  for  GEOS  disk 

tax  /put  in  x  in  case  error 

bne  99$ 

LoadW  r4,#diskBlkBuf  ;get  off-page  block 

jsr  Get Block  / 

99$:    rts  /  return  with  error  in  x 
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GetPathnamejAppie) 


high-level  disk 


Function: 
Parameters: 

Uses: 
Returns: 

Alters: 
Destroys: 
Description: 


Builds  out  an  ASCII  pathname  string  to  any  disk  directory. 

rl        PATHBUF  —  pointer  to  buffer  to  place  pathnanie  (word). 
rOL      BUFSIZE  —  size  of  pathname  buffer  (byte). 

t2        KEYBLKNO  —  key  block  of  directory  to  build  path  for;  pass  the  value 
in  curKBIkno  to  get  the  path  of  the  current  directory. 

curDrive 

X  error  ($00  =  no  error). 

y  pathname  status  ($00  =  OK;  BFR_OVERFLOW  =  pathname  longer 

than  jBC/F5/Z£  bytes). 


diskBlkBuf 
a,  rO-r2L,  r4. 


used  to  hold  temporary  blocks. 


GetPathname  works  backward  from  the  directory  specified  by  KEYBLKNO, 
building  out  a  pathname  in  the  buffer  pointed  to  by  PATHBUF.  The  pathname  is 
built  up  in  ASCII  from  right  to  left.  If  the  actual  path  is  larger  than  BUFSIZE 
bytes,  the  lowest  BUFSIZE  characters  of  the  path  are  placed  in  the  buffer  and  a 
BFR^O VERFLOW  error  is  returned. 

C64  &  C 128 :  CtominodoreGEOS  does  not  support  a  hierarchical  file  system. 
Example: 

See  also:     GoDirectory,  UpDirectory,  DownDirectory. 
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GetPattern  (Apple) 


graphics! 


Function: 
Parameters: 

Returns: 

Destroys: 
Description: 


Example: 
See  also: 


Copy  an  eight-byte  GEOS  pattern  definition  to  an  application's  buffer. 

a       GEOS  system  pattern  number. 

rO      pointer  to  eight-byte  destination  buffer  (word). 

rO  unchanged. 

Pattern  data  in  buffer  pointed  to  by  rO 

a,y 

GetPattern  downloads  an  eight-byte  pattern  definition  from  auxiliary  high 
memory  to  a  buffer  defined  by  the  application.  This  is  the  only  convenient  way  to 
gain  access  to  the  system  pattern  definitions  under  Apple  GEOS.  To  redefine  a  fill 
pattern,  use  SetUserPattern. 


SetPattern,  SetUserPattern. 


CONriDCNTIAL 
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GetPtrCurDkNm 


GetPtrCurPkNm  (Apple,  C64,  cns) 


high-level  dlsk| 


Function: 
Parameters: 

Uses: 
Returns: 

Destroys: 
Description: 


Get  pointer  to  the  current  disk  name. 

X       PTR  —  zero-page  address  to  place  pointer  (byte  pointer  to  a  word 
variable). 


curDrive 


currendy  active  drive. 


X  unchanged. 

zero-page  word  at  $00,x  {PTR)  contains  a  pointer  to  the  current  disk  name. 

GetPtrCurDkNm  returns  an  address  that  points  to  the  name  of  the  current  disk. 
Disk  names  are  stored  in  the  Dr;cCurDkNm  variables,  where  x  designates  the 
drive  (A,  B,  C,  or  D).  If  drive  A  is  the  current  drive  then  GetPtrCurDkNm 
would  return  the  address  of  DrACurDkNm.  If  drive  B  is  the  current  drive  then 
GetPtrCurDkNm  would  return  the  address  of  DrBCurDkNm.  And  so  on. 

Although  the  locations  of  the  Dr;cCurDkNm  buffers  are  at  fixed  memory 
locations,  they  are  not  contiguous  in  memory.  It  is  easier  to  call 
GetPtrCurDkNm  than  hardcode  the  addresses  into  the  application.  This  will 
also  ensure  upward  compatibilty  with  future  versions  of  GE(DS  that  might  support 
more  drives. 

C64:  Versions  of  GEOS  before  vl.3  only  suport  two  disk  drives  and  therefore  only 

have  two  disk  name  buffers  allocated  (DrACurDkNm  and  DrBCurDkNm). 
GEOS  vl.3  and  later  support  additional  drives  C  and  D.  GetPtrDkNm  will 
return  the  proper  pointer  values  in  any  version  of  GEOS  as  long  as.numDrives 
does  not  exceed  the  number  of  disk  name  buffers.  Trying  to  get  a  pointer  to 
DrDCurDkNm  under  GEOS  vl.2  will  return  an  invalid  pointer  because  the 
buffer  does  not  exist 

C64  &  C128:  Ctommoodore  disk  names  are  always  a  fixed-length  16  character  string.  If  the 
name  is  less  than  16  characters,  the  string  is  padded  with  $aO. 


Apple: 

Example: 
See  also: 


Apple  disk  names  are  null-terminated  strings  of  16  characters  or  less  (counting  the 
null-temiinator). 
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GetRandom 


IGetRandom  (Apple,  C64,  cus) 


uti 


mt3 


Function: 

Parameters: 

Uses: 

Alters: 

Destroys: 

Description: 


Note: 


Creates  a  16-bit  random  number, 
none. 

random  seed  for  next  random  number, 

random  contains  a  new  16-bit  random  number, 

a 

GetRandom  produces  a  new  pseudorandom  (not  truly  random)  number  using 
the  following  linear  congmential  formula: 

random  =  (2*(random+l)  //  65521) 

(remember:  II  is  the  modulaus  operator) 

The  new  random  number  is  always  less  than  65221  and  has  a  fairly  even 
distribution  between  0  and  65521 . 

GEOS  calls  GetRandom  during  Interrupt  Level  processing  to  automatically  keep 
the  random  variable  updated.  If  the  application  needs  a  random  number  more 
often  than  random  can  be  updated  by  the  Kemal,  then  GetRandom  must  be 
called  manually 


Example: 
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GetRealSize 


GetRealSize  (Apple,  C64,  cus) 


Function:       Calculate  the  printed  size  of  a  character  based  on  any  style  attributes. 

Parameters:    a       CHAR  —  character  code  of  character  (byte). 

X       MODE  —  style  mode  (as  stored  in  currentMode). 

Uses:  curHeight 

baselineOffset 

Apple; 

lastWIdth  (if  character  code  is  USELAST) 

Returns:        y       character  width  in  pucels  (with  attributes). 

X       character  height  in  pixels  (with  attributes), 
a       character  baseline  offset  (with  attributes). 

Destroys:  nothing. 

Calls:  GetCharWidth 

Description:  GetRealSize  calculates  the  width  of  the  character  based  any  style  attributes  The 
character  code  must  be  32  or  greater.  If  the  character  code  is  USELAST,  the 
value  in  lastWidth  is  returned.  Any  other  character  code  returns  the  pixel  width 
as  calculated  from  the  font  data  structure  and  the  MODE  parameter. 

C64  &  C128:  lastWidth  is  local  to  the  GEOS  Kemal  and  therefore  inaccessible  to  applications. 
It  contains  the  actual  width  of  the  most  recendy  printed  character. 

See  also:  GetCharWidth. 

Example: 

;  Calculate  size  of  largest  character  in  current  font 

Ida  #'W'  ;  capital  W  is  a  good  choice 

Idx  #(SET_BOLD|SET_OUTLINE  ;  widest  style  combo 

jsr  GetRealSize  ;  dimensions  come  back  in  x,y 


text 
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GetScanLine 


GetScanLine  (Apple,  C64,  cm) 


graphics] 


Function: 

Parameters: 

Uses: 

Returns: 


Destroys: 
Description: 


Calculate  the  memory  address  of  a  particular  screen  line. 
X        Y  —  y-coordinate  of  line. 

dispBufferOn: 

bit  7  —  calculate  foreground  screen  address, 
bit  6  —  calculate  background  buffer  address. 

X  unchanged. 

addresses  in  rS  and  r6  based  on  dispBufferOn  status: 
bit  7    bit  6  returns 


1 

1 

rS  =  foreground;  i6  s  backKround 

0 

1 

r5.  r6  =  background 

1 

0 

r5.  i6  =»  foreRTOund 

0 

0 

error:  r5/6  =  address  of  screen  center 

a 

GetScanLine  calculates  the  address  of  the  first  byte  of  a  particular  screen  line. 
The  routine  always  places  addresses  in  both  rS  and  r6,  depending  on  the  value  in 
dispBufferOn.  This  allows  an  application  to  automatically  manage  both 
foreground  screen  and  background  buffer  writes  according  to  the  bits  set  in 
dispBufferOn  by  merely  doing  any  screen  stores  twice,  indirectly  off  both  rS 
and  r6  as  in: 


Note:  this  code  is  C64  specific  (see  notes  below  for  128  and  Apple) 


128: 


Apple: 


Idy 
Ida 
sta 
sta 


xpos 
grByte 
(r5),y 
(r6),y 


byte  index  into  current  line 
graphics  byte  to  store 
store  using  both  indexes 


When  GEOS  128  is  operating  in  80-column  mode,  all  foreground  writes  are  sent 
through  the  VDC  chip  to  its  local  RAM.  In  this  case,  the  address  of  the 
foreground  screen  byte  is  actually  an  index  into  VDC  RAM  for  the  particular 
scanline.  For  background  writes,  the  address  of  the  background  screen  byte  is  an 
absolute  address  in  main  memory  (be  aware,  though,  that  the  background  screen 
is  broken  into  two  parts  and  is  not  a  contiguous  chunk  of  memory). 

In  40-column  mode,  GetScanLine  operates  as  it  does  under  GEOS  64. 

Because  the  Apple  double  hi-res  screen  is  spread  across  two  memory  banks,  it  is 
sometimes  necessary  to  enable  or  disable  a  given  bank  before  accessing  the 
screen.  The  following  subroutine  >yill  swap  in  the  correct  memory  bank: 

Routine  to  set  correct  memory  bank  in  Apple 

Pass:  a  -  byte  index  into  line  (xpos) 

Returns:  proper  memory  bank  swapped  in 

y  -  corrected  index  into  line 


129 


GetScanLine 


/Destroys:  a 

•  *****1ir********«******«4r****«r*ir  ************  ******* 

SetCorrectPage : 

Isr  a  ;xpos/2;  low-bit  into  carry 

tay  /return  correct  index  in  y 

bcs  10$  /Is  low-bit  set? 

St  a  PAGE2__0N  / — >N0:  swap  in  aux.  memory 

rts  /  return 

10$: 

sta  PAGE2_0FF  / — >YES:  swap  in  main  memory 

rts  /  return 

Example: 
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GetScreenLi 


IGetScreenLine  (Apple) 


graphics 


Function: 
Parameters: 


Uses: 

Returns: 

Destroys: 

Description: 


Note: 
Example: 


Copies  a  byte-aligned  horizontal  line  from  the  screen,  in  internal  format,  to  an 
application's  buffer. 

rO      DATA  —  address  of  buffer  to  copy  data  to  (word). 
rlH    XINDX  —  byte  in  line  to  begin  with  (seven-bit  Apple  screen  byte)  (byte). 
r2L    XWIDTH  —  width  in  bytes  of  line  (seven-bit  Apple  screen  bytes)  (byte). 
rIL    Y  —  y-coordinate  of  line  (byte). 

where  (XINDX*7,Y)  and  (XINDX^J-^XWIDTHJ)  define  the  endpoints  of  the 
line. 

dispBufferOn: 

bit  7  —  get  data  from  foreground  screen  if  set 
bit  6  —  get  data  from  background  buffer  if  set. 
If  both  bits  are  set,  foreground  screen  is  used. 

rO      address  of  byte  following  last  byte  in  line. 

a,  X,  y,  rO,  rlH 

GetScreenLine  copies  bytes  direcdy  from  the  screen  memory  to  the  specified 
buffer.  The  screen  is  treated  as  a  contiguous  block  of  bytes  even  though,  in 
actuality,  alternate  bytes  lie  in  different  memory  banks. 

Bytes  are  copied  into  the  buffer  pointed  to  by  rO  beginning  at  the  byte-index  into 
the  line  stored  in  rlH. 

No  clipping  at  the  screen  edge  is  performed;  the  values  passed  are  assumed  to  lie 
entirely  on  one  screen  line. 


131 


GetSerialNumber 


GetSerialNumber  (Apple,  C64,  ci28)   internal 


Function:  Return  the  16-bit  serial  number  or  pointer  to  the  serial  string  for  the  current  GEOS 
kemaL 

Parameters:  none. 

Returns:  Commodore: 

rO      16-bit  serial  number. 

Appig; 

rO      pointer  to  serial  string. 
Destroys:  a. 

Description:  GetSerialNumber  gives  an  application  access  to  an  unencrypted  copy  of  the 
GEOS  serial  number  or  serial  string  for  comparison  purposes.  You  cannot  change 
the  actual  serial  string  or  number  by  altering  this  copy. 
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GetSpriteData 


GetSpritePata  (Apple) 


sprite! 


Function: 

Parameters: 

Returns: 

Destroys: 

Description: 

Note: 


Example: 
See  also: 


Copies  a  64-byte  sprite  image  from  the  internal  data  buffer  that  is  used  for 
drawing  the  sprites  to  the  application's  memory  space. 

r3L    SPRITE  —  sprite  number  (byte). 

r4      BUFPTR  —  pointer  to  64-byte  buffer  (word). 

sprite  data  in  buffer  pointed  to  by  BUFPTR. 

a,y 

GetSpriteData  is  the  functional  opposite  of  DrawSprite.  It  copies  64-bytes  of 
sprite  image  data  from  the  internal  buffer  that  is  used  for  drawing  the  sprites  to  a 
buffer  in  the  application  memory  space. 

In  no  case  should  the  SPRITE  parameter  be  $00;  a  value  of  $00  will  return 
incorrect  data. 

The  INAUX^B  constant  may  be  or'ed  into  the  SPRITE  parameter  to  indicate 
that  the  BUFPTR  parameter  is  an  address  in  auxiliary  memory. 


DrawSprite,  PosSprite,  EnablSprite,  DisablSprite,  InitSprite. 
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GetString 


GetString  (Apple,  C64,  ci28) 


text/keyboard  I 


Uses: 


Returns: 


Destroys: 


rlL 

r2L 

rll 
rlH 


r4 


Function:       Get  a  string  from  the  keyboard  using  a  cursor  prompt  and  echoing  characters  to 
the  screen  as  they  are  typed  Runs  concurrently  with  MainLoop. 

Parameters:    rO  BUFR  —  pointer  to  string  buffer.  When  called  this  buffer  can 

contain  a  null-terminated  default  string  (if  no  default  string  is  used, 
the  first  byte  of  the  buffer  must  be  NULL).  This  buffer  must  be  at 
least  MAX  C//+1  bytes  long. 

FLAG  — "$00  =  use  system  fault  routine;  $80  =  use  fault  routine 
pointed  to  by  r4  (byte). 

MAX.CH  —  maximum  number  of  characters  to  accept  (not 
including  the  nuU-terminator). 
XPOS  —  x-coordinate  to  begin  input  (word). 
YPOS  —  y-coordinate  of  prompt  and  upper-left  of  characters.  To 
calculate  this  value  based  on  baseline  printing  position,  subtract  the 
value  in  baselineOffset  from  the  baseline  printing  position  (byte). 
FAULT  —  optional  (see  FLAG)  pointer  to  fault  routine, 
key  Vector  STRINGDONE  —  routine  to  call  when  the  string  is  terminated  by 
the  user  typing  a  carriage  return.  $0000  =  no  routine  provided. 

at  call  to  GetString: 

curHeight  for  size  of  text  prompt. 

baselineOffset     for  positioning  default  string  relative  to  prompt 
any  variables  used  by  PutString. 

while  accepting  characters: 

key  Vector  vectors  off  of  MainLoop  through  here  with  characters. 

stringX  current  prompt  x-position. 

stringY  current  prompt  y-position. 

string  pointer  to  start  of  string  buffer, 

any  variables  used  by  PutChar. 

from  call  to  GetString: 

keyVector  address  of  SystemStringService. 

stringFaultVec    address  of  fault  routine  being  used 
StringX  starting  prompt  x-position. 

StringY  starting  prompt  y-position. 

string  BUFR  (pointer  to  start  of  string  buffer). 

when  done  accepting  characters: 

X  length  of  string;  index  to  null,  relative  to  address  in  string, 

string  BUFR  (pointer  to  start  of  string  buffer). 

keyVector  $0000 
StringFaultVec  $0000 

at  call  to  GetString: 
r0-rl3,  a,  x,  y. 

Description:  GetString  installs  a  character  handling  routine  into  keyVector  and  returns 
immediately  to  the  caller.  During  MainLoop,  the  string  is  built  up  a  character  at  a 
time  in  a  buffer.  When  die  user  presses  [Return],  GEOS  calls  die  STRINGDONE 
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GetString 


routine  with  the  starting  address  of  the  string  in  string  and  the  length  of  the 
string  in  the  x-register. 

The  following  is  a  breakdown  of  what  GetString  does: 

1:  Variables  local  to  the.GetString  character  input  routine  are  initalized.  Global 
string  input  variables  such  as  string,  stringX,  and  stringY  are  also 
initialized. 

2:  PutString  is  called  to  output  the  default  input  string  stored  in  tiie  character 
buffer.  If  no  default  input  string  is  desired,  the  first  byte  of  tiie  buffer  should 
be  a  NULL. 

3:  The  STRINGDONE  parameter  in  key  Vector  is  saved  away  and  the  address 
of  the  GetString  character  routine  (SystemStringService)  is  put  into 
keyVector. 

4:  If  tiie  application  supplied  a  fault  routine,  install  it  into  StringFaultVec, 
otherwise  install  a  default  fauh  routine. 

5:  The  prompt  is  initalized  by  calling  InitTextPrompt  with  the  value  in 
curHeight.  PromptOn  is  also  called. 

6:  Control  is  returned  to  the  application. 

C64  &C128:  String  is  not  null-terminated  until  tiie  user  presses  [Return].  To  simulate  a 
[Return],  use  die  following  code: 

/Simulate  a  CR  to  end  GetString 

LoadB        keyData,#CR  /load  up  a  (Return) 

Ida  keyVector  /and  go  through  keyVector 

Idx  keyVector+1  /so  SystemStringService 

jsr  CallRoutine  /thinks  it  was  pressed 

Note  that  tiiis  will  also  terminate  tiie  GetString  input. 
Apple:  String  is  always  kept  null-terminated. 

Note:  This  note  courtesy  of  Bill  Coleman.. .Because  GetString  runs  off  of 

MainLoop,  it  is  a  good  idea  to  call  GetString  from  the  top  level  of  the 
application  code  and  return  to  MainLoop  while  characters  are  being  input.  That 
is,  while  at  the  top  level  of  your  code  you  can  call  GetString  like  this: 

jsr  GetString  /  Start  GetString  going 

rts  /  and  return  immediately  to  MainLoop  so 

/  that  string  can  be  input. 

Since  the  routine  specified  by  the  STRINGDONE  value  stored  in  key  Vector  is 
called  when  the  user  has  finished  entering  the  string,  that  is  where  your 
application  should  again  take  control  and  process  the  input. 

See  also:       PutChar,  PutString,  GetNextChar. 

Example: 
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GetVBM 


GetVBM  (Apple) 


mid-level  disk 


Function: 

Parameters: 

Uses: 

Returns: 
Alters: 


Destroys: 
Description: 


Note: 

Example: 
See  also: 


Read  the  first  (or  only)  VBM  block  into  the  internal  VBM  cache, 
none. 


curDrive 
VBMBlknot 


block  number  of  first  VBM  block. 


error  ($00  =  no  error). 


curVBlkno^ 

VBMchanged^ 

numVBMBlkst 


block  loaded  into  cache. 

set  to  FALSE;  indicates  current  cache  matches  disk, 
number  of  VBM  blocks. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
a,  y,  rl,  r4. 

GetVBM  reads  the  first  block  of  the  VBM  (volume  bit  map)  into  the  internal 
VBM  cache.  This  cache  is  inaccessible  to  applications  but  is  used  indirectly  by 
routines  such  as  SetNextFree.  GetVBM  is  called  automatically  by  OpenDisk 
and  ReOpenDisk  to  get  a  valid  VBM  block  into  the  cache.  Specialized 
applications  that  switch  disks  or  drives  without  using  OpenDisk  or 
ReOpenDisk,  should  call  GetVBM  to  erase  any  VBM  bits  from  a  previous 
disk  tiiat  might  be  lurking  in  the  cache. 

For  mon  information  on  Apple  GEOS  VBM-cacheing,  refer  to  PutVBM. 

« 

GetVBM  ignores  the  VBMchanged  flag.  The  block  is  always  read  in  from 
disk,  overwriting  whatever  is  currendy  in  the  cache. 


PutVBM,  GetDirHead,  PutDirHead. 
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GoDirectory 


GoDirectory  (Apple) 


mid-level  disk  I 


Function: 

Parameters: 

Uses: 

Returns: 
Alters: 


Destroys: 


Go  to  a  specific  directory  on  the  disk,  making  it  the  current  directory. 

rO        KEYBLKNO  —  block  number  of  this  directory's  key  block  (word). 


curDrive 
curKBlkno 


current  directory. 


X         error  ($00  =  no  error). 

y         pathname  stanis  ($00  =  OK;  BFR^OVERFLOW  =  pathname  longer 
than  pathnameBuf)- 


curKBlkno 

curDirHead 

pathnameBur 

curDirTabLot 

curDirTabHit 


new  current  directory, 
header  of  new  directory. 

system  pathname  buffer  updated  to  reflect  new  path, 
system  directory  table 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
a,  rOL,  rl,  r2,  r4. 


Description:   GoDirectory  makes  the  directory  at  KEYBLKNO  the  current  working  directory 
so  that  all  operations  happen  within  it . 

GoDirectory  first  changes  the  current  key  block  number,  then  calls 
GetPathname  to  build-out  the  full  pathname  in  pathnameBuf.  The  current 
directory  header  is  read  in  with  a  call  to  GetDirHead 

€64  &  C128:  Commodore  GEOS  does  not  support  a  hierarchical  file  system. 

Example: 

See  also:     UpDirectory,  DownDirectory. 
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GotoFirstMenu 


IGotoFirstMenu  (Apple,  C64,  cm) 


icon/menu 


Function: 


Retracts  all  sub-menus  and  reactivates  nienus  at  the  main  menu  level 


Parameters:  none- 

Destroys:       assume  r0-rl5,  a,  x,  y 


Description: 


GotoFirstMenu  is  used  by  a  menu  event  handler  to  instruct  GEOS  to  back  up 
to  the  main  menu  level,  erasing  the  current  menu  and  any  parent  menus  (except 
the  main  menu)  from  the  foreground  screen,  making  the  main  menu  active  when 
control  is  returned  to  MainLoop.  menuNumber  is  set  to  $00. 


GotoFirstMenu  can  be  called  from  a  menu  event  routine  at  any  menu  level, 
including  main  menu  level.  It  operates  by  checking  for  level  zero  and  calling 
DoPreviousMenu  in  a  loop. 

Example: 

See  Also:       DoMenu,  DoPreviousMenu,  ReDoMenu,  RecoverAIlMenus. 
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HideOnlyMouse 


HideOnlyMouse  (Apple,  cns) 


mouse/sprite! 


Function:  Temporarily  removes  the  soft-sprite  mouse  pointer  firom  the  graphics  screen. 
Parameters:  nothing. 


Returns: 
Uses: 

Alters: 

Destroys: 

Description: 


128: 


Apple: 


Example: 
See  also: 


nothing. 

graphMode 
offFIag 

offFlag 

a,  X,  y,  rl-r6 


(128  only). 
(Apple  only). 

set  to  TRUE  (Apple  only). 


HideOnlyMouse  temporarily  removes  the  mouse-pointer  soft-sprite.  It  does  not 
affect  any  of  the  other  sprites.  This  can  be  used  as  an  alternative  to 
TempHideMouse  when  only  the  mouse  pointer  need  be  hidden.  The  mouse 
pointer  will  remain  hidden  until  die  next  pass  through  MainLoop.  Any 
subsequent  calls  to  TempHideMouse  before  passing  through  MainLoop 
again  will  not  erase  any  sprites. 

In  40-column  mode  (when  bit  7  of  graphMode  is  zero),  HideOnlyMouse 
exits  immediately  without  affecting  the  hardware  sprites.  Also,  be  aware  that  any 
subsequent  GEOS  graphic  operation  will  hide  any  visible  sprites  by  calling 
TempHideMouse,  so  this  routine  is  not  especially  usefuU  if  using  GEOS 
graphics  routines. 

This  routine  sets  offFlag  to  TRUE  which  will  stop  TempHideMouse  from 
erasing  any  sprites  until  the  soft-sprite  handling  code  in  MainLoop  is 
encountered.  In  some  cases  this  causes  problems  with  graphic  operations  that 
occur  off  of  MainLoop  before  this  code  is  executed.  The  easiest  solution  to  this 
problem  is  to  avoid  using  HideOnlyMouse  and  use  TempHideMouse  with 
noEraseSprites  set  to  TRUE.  offFlag  can,  instead,  be  set  to  $40  if  die 
application  wants  the  GEOS  Interrupt  Level  to  redraw  the  mouse  before  the 
application  returns  to  MainLoop. 


TempHideMouse. 
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HorizontalLine 


IHorizontalLine  (Apple,  C64,  cns) 


graphics! 


Function: 
Parameters: 


Uses: 

Returns: 
Destroys: 


Draw  a  horizontal  line  with  a  repeating  bit-pattern. 

a       PATTERN  —eight-bit  repeating  pattern  to  use  (not  a  GEOS  pattern 
number), 

r3      XI  —  x-coordinate  of  leftmost  endpoint  (word). 
r4      X2  —  x-coordinate  of  rightmost  endpoint  (woid). 
rllL  Yl  —  y-coordinate  of  line  (byte). 

where  (XI, Yl)  cind  (Xljl)  define  the  endpoints  of  the  horizontal  line. 

dispBufferOn: 

bit  7  —  write  to  foreground  screen  if  set. 
bit  6  —  write  to  background  screen  if  set 


nothing 

Commodore 
a,  X,  y,  r5-r8,  rllH 

Apple 

a,  X,  y,  rllH 

Description:  HorizontalLine  sets  and  clears  pixels  on  a  single  horizontal  line  according  to 
the  eight-bit  repeating  pattern.  Wherever  a  1-bit  occurs  in  the  pattern  byte,  a  pixel 
is  set,  and  wherever  a  0-bit  occurs,  a  pixel  is  cleared 

Bits  in'the  pattern  byte  are  used  left-to-right  where  bit  7  is  at  the  left  .A  bit  pattern 
of  %  1 1 1 100(X)  would  create  a  horizontal  line  like: 


Note: 


128: 


Example: 
See  also:. 


The  pattern  byte  is  always  drawn  as  if  aligned  to  a  card  boundary.  If  the 
endpoints  of  a  line  do  not  coincide  with  card  boundaries,  then  bits  are  masked  off 
the  appropriate  ends.  The  effect  of  this  is  that  a  pattern  is  always  aligned  to 
specific  pixels,  regardless  of  the  endpoints,  and  that  adjacent  lines  drawn  in  the 
same  pattern  will  align. 

To  draw  patterned  horizontal  lines  using  the  8x8  GEOS  patterns,  draw  rectangles 
of  one-pixel  height  by  calling  the  GEOS  Rectangle  routine  with  identical  y- 
coordinates. 

Under  GEOS  128,  or'ing  DOUBLE  W  into  theXi  andX2  parameters  will 
automatically  double  the  x-posiuon  in  ^-column  mode.  Or'ing  in  ADDl^W  will 
automatically  add  1  to  a  doubled  x-position.  (Refer  to  "GEOS  128  X-posiBon  and 
Bitmap  Doubling"  in  Chapter.®  gr@  for  more  information.) 


VerticalLine,  InvertLine,  ImprintLine,  RecoverLine,  DrawLine. 
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Printline 


ImprintLine  (Apple) 


graphics! 


Function: 
Parameters: 


Returns: 

Destroys: 

Description: 

Note: 


Example: 
See  also: 


Imprints  a  horizontal  line  fix)m  the  foreground  screen  to  the  background  buffer. 

r3      XI  —  x-coordinate  of  leftmost  endpoint  (word). 
r4      X2  —  x-coordinate  of  rightmost  endpoint  (word), 
r  1 1 L  Y 1  —  y-coordinate  of  line  (byte). 

where  (XI, Yl)  and  (X2,Y1)  define  the  endpoints  of  the  line  to  imprint. 

nothing 

a,  X,  y 

ImprintLine  imprints  the  pixels  which  fall  on  the  horizontal  line  whose 
coordinates  are  passed  in  the  GEOS  registers.  The  pixel  values  are  copied  from 
the  foreground  screen  to  the  background  buffer. 

The  flags  in  dispBufferOn  are  ignored;  the  pixels  are  always  copied  to  the 
background  buffer  regardless  of  the  value  in  this  variable. 

This  routine  does  not  exist  in  GEOS  64  or  GEOS  128.  Use  ImprintRectangle 
with  a  height  of  one. 


RecoverLine,  HorizontalLine,  InvertLine,VerticalLine  ,  DrawLine. 
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ImprintRectangle 


ImprintRectangle^  i  ImprintRectangle  (Apple,  C64,  cns)  graphics] 


Function: 


Parameters: 


Returns: 
Destroys: 


Description: 

Note: 
128: 


Example: 
See  also: 


Imprints  the  pixels  within  a  rectangular  region  from  the  foreground  screen  to  the 
background  buffer. 

Normal: 

r3      XI  —  x-coordinate  of  upper-left  (word). 
r2L    Yl  —  y-coordinate  of  upper-left  (byte)- 
r4      X2  —  x-coordinate  of  lower-right  (word), 
r 2  H    Y2  —  y-coordinate  of  lower-right  (byte). 

Inline: 

data  appears  immediately  after  the  jsr  i_ImprintRectangle 
.byte   Yl    y-coordinate  of  upper-left. 
.byte   Y2   y-coordinate  of  lower-right, 
.word  XI   x-coordinate  of  upper-left, 
.word  X2   x-coordinate  of  lower-right. 

where  (XI, Yl)  is  the  upper-left  corner  of  the  rectangular  area  and  (X2,Y2)  is  the 
lower-right  corner. 

nothing 

CpmrnodQi? 

a,  X,  y,  r5-r8,  rllL 

Apple 

a,  x,y,  rllL 

ImprintRectangle  copies  the  pixels  within  a  rectangular  region  from  the 
foreground  screen  to  the  background  buffer  by  calling  ImprintLine  in  a  loop.  A 
subsequent  call  to  RecoverRectangle  with  the  same  parameters  will  restore  the 
rectangle  to  the  foreground  screen. 

The  flags  in  dispBufferOn  are  ignored;  the  pixels  are  always  copied  to  the 
background  buffer  regaixlless  of  the  value  in  this  variable. 

Under  GEOS  128,  or'ing  DOUBLE  W  into  the  XI  andX2  parameters  will 
automatically  double  the  x-position  in  SD-column  oKxie.  Or'ing  in  ADDl^W  will 
automatically  add  1  to  a  doubled  x-position.  (Refer  to  "GEOS  128  X-posinon  and 
Bitmap  Doubling"  in  Chapter.®  gr@  for  more  information.) 


RecoverRectangle,  Rectangle,  InvertRectangle. 
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InfoCard 


InfoCard  (Apple)  card  driver 


Function:       Get  information  about  the  cuirent  printer  card- 
Parameters:  none. 

Returns:        x          STATUS  —  card  error  code;  $00  =  no  error  (byte) 
y  TYPE;  


b7 

0:  seven-bit  data  card. 
1:  eight-bit  datacard. 

b6 

0:  serial  interface  card. 
1:  parallel  interface  card. 

b5 

0:  card  only  capable  of  output 
1 :  card  capable  of  input  and  output. 

b4 

0:  does  not  support  StatusCard  ready-for-output  flag. 
1:  supports  StatusCard  ready-for-output  flaj?. 

b3 

0:  does  not  support  StatusCard  input-ready  flag. 
1:  supports  StatusCard  input-ready  flag. 

Destroys:  a. 

Description:  InfoCard  returns  information  about  the  installed  card. 

Note:  This  routine  may  be  called  at  any  time. 

Example: 

See  also:  StatusCard. 
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InitCa 


InitCard  (Apple)    card  driver} 


Function:       Initialize  printer  card- 
Parameters:    rO-rlL  SERIALCONFIG  —  card  configuration  information  for  serial  I/O  cards; 

parallel  cards  do  not  use  this  information  (three  bytes). 

Returns:        x  STATUS  —  card  error  code;  $00  =  no  error  (byte) 

Destroys:       assume  a,  y. 

Description:  InitCard  performs  the  basic  initialization  and  configuration  of  a  printer  card.  A 
printer  driver  will  usually  perform  this  operation  from  InitForPrint.  InitCard 
configures  the  printer  card  with  a  three-byte  set  of  CONFIG  parameters. 


The  COA/F/G  Values: 

Most  Apple  printer  cards  use  die  standard  65xx  series  6551  ACIA  (Asynchronous 
Communications  Interface  Adapter)  to  communicate  between  the  Apple  bus  and 
the  printer.  The  CONFIG  bits  directly  reflect  the  available  configurations  for  this 
chip.  Bits  mauriced  as  unused  are  either  unused  on  the  chip  or  forced  to  a  specific 
state  by  the  card  driver.  For  more  information,  refer  to  the  RM  65  Family 
Asynchronous  Communications  Interface  Adapter  (ACIA)  Module  User's  Manual 
(Rockwell  International). 


rOL:    control  register. 

bits  description 


b7 

0: 

one  stop  bit. 

1: 

1-1/2  stop  bits  with  five  data  bits  and  no  parity. 

one  stop  bit  with  eight  data  bits  and  parity. 

two  stop  bits  in  all  other  cases. 

b6-b5 

00: 

8  data  bits. 

01: 

7  data  bits. 

10: 

6  data  bits. 

11: 

S  data  bits. 

b4 

mused. 

b3-bO 

0000 

undefined. 

0001 

SO  baud. 

0010 

75  baud. 

0011 

109.92  (110)  baud. 

0100 

134.56  (135)  baud. 

0101 

150  baud. 

Olio 

300  baud. 

0111 

600  baud. 

1000 

1200  baud. 

1001 

1800  baud. 

1010 

:  2400baud. 

1011 

:  3600baud. 

1100 

:        4800  baud. 

1101 

:         7200  baud. 

1110 

:         9600  baud. 

nil 

:         19200  baud  (19.2  Kbaud). 

rOH:    command  register. 
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tCard 


bits 

description 

b7-b6 

00 
01 
10 

11 

odd  parity, 
even  parity, 
marie  pari^. 
space  parity. 

b5 

0 

1 

parity  disabled  (no  parity,  ignore  b7-b6). 
parity  enabled. 

b4-b0 

undefined. 

handshaking, 
bits  description 

b7 

0 
1 

do  not  check  for  XOFF. 
detect  XOFF.  wait  for  XON. 

b6-b5 

00 

11 

ignore  hardware  handshaking, 
follow  hardware  handshaking. 

M 

must  be  1. 

b3-bO 

must  be  000 

Most  serial  printers  operate  with  eight  data  bits,  no  parity,  and  one  stop  bit  Some 
printers,  like  the  Apple  LaserWriter  require  two  stop  bits. 

Note :  InitCard  must  be  called  before  OpenCard. 

Example: 

See  also:  OpenCard. 
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InltForDial 


InitForPialOg  (Apple)  intcmall 

Function:       Saves  away  the  state  of  GEOS  as  if  about  to  pass  control  to  a  dialog  box. 
Parameters:  none. 

Returns:        system  initialized  to  a  near-wamistart  state. 
Destroys:       a,x,  y,  r0-r4 

Description:  Prior  to  displaying  a  dialog  box,  DoDIgBox  saves  away  the  state  of  the 
application  in  an  internal  buffer  and  then  reinitializes  GEOS  so  that  the  dialog  box 
runs  as  if  it  were  an  independent  application.  This  allows  a  dialog  box  to  use 
nearly  all  the  facilities  of  GEOS  without  disrupting  the  parent  application.  This 
facility  for  temporarily  suspending  the  state  of  GEOS  is  potentially  useful  in  an 
application  and  can  be  accessed  by  calling  InitForDialog. 

InitForDialog  saves  off  the  current  system  state  and  then  places  GEOS  in  a 
near-warmstart  state.  To  return  GEOS  to  its  previous  state,  call 
RecoverSysRam. 

Note:  Calls  to  InitForDialog  cannot  be  nested  because  GEOS  can  only  buffer  its  state 

to  a  depth  of  one  level.  A  second  call  to  InitForDialog  without  calling 
RecoverSysRam  will  overwrite  the  saved  state  of  the  system  with  the  current 
state.  Because  DoDIgBox  calls  InitForDialog  as  part  of  its  normal  operation, 
it,  too,  will  overwrite  the  saved  state  of  the  system. 

See  also:  RecoverSysRam. 


CONriDCNTlAL 
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InltForlO 


InitForlO  (C64,  ci28) 


very  low>level  disk 


Function: 


Prepare  for  I/O  across  the  serial  bus- 


Parameters: 


none. 


Returns: 


nothing. 


Destroys:       a,  y. 

Description:   InitForlO  prepares  the  system  to  perform  I/O  across  the  Commodore  serial  bus. 


It  disables  interrupts,  turns  sprite  DMA  off,  slows  the  128  down  to  IMhz, 
switches  in  the  ROM  and  I/O  banks  if  necessary,  and  performs  anything  other 
initialization  needai  for  fast  serial  transfer. 

Call  InitForlO  before  directly  accessing  the  serial  port  (e.g.,  in  a  printer  driver) 
or  before  using  ReadBIock,  WriteBIock,  VerWriteBIock,  or  ReadLink. 
To  restore  the  system  to  its  previous  state,  call  DoneWithlO. 


Apple: 


Apple  GEOS  has  no  InitForlO  equivalent 


Example: 


See  WriteBIock. 


See  also: 


DoneWithlO,  SetDevice. 
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InitForPrInt 


InitForPrint  (Apple,  C64,  cns) 


Initialize  printer.  Perform  once  per  document 
none. 

Commodore 
nothing. 

Apple 

X  STATUS  —  printer  error  code;  $00  =  no  error. 

Commodore 

assume  a,  x,  y,  r0-rl5. 
Applg 

assume  a,  y,  r0-rl5. 

InitForPrint  performs  any  initialization  necessary  to  prepare  the  printer  for  a 
GEOS  document.  Often  this  involves  resetting  the  printer  to  bring  it  into  a  default 
state  as  well  as  suppressing  automatic  margins  and  perforation  skipping. 
InitForPrint  does  not  do  any  initialization  specific  to  graphic  or  ASCII  printing. 

Commodore:  InitForPrint  is  also  used  to  set  the  printer  baud  rate  for  serial  printers. 

Apple:  Some  printer  drivers  may  try  to  send  a  non-printing  character  to  the  printer  to 

ensure  that  it  is  ready  to  accept  data.  If  the  printer  is  not  ready,  InitForPrint  will 
return  a  PR  TIME_OUT  error.  This  usually  means  the  printer  is  switched  off 
or  is  not  online:  Many  printer  drivers,  however,  will  do  no  such  checking  and 
have  no  facility  for  detecting  a  printer  time-out 

See  also:       StartPrint,  StartASCII. 
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printer  driver 


Function: 

Parameters: 

Returns: 

Destroys: 

Description: 


InitMouse 


InitMoUSe  (Apple,  C64,  C128) 


input  driver 


Function: 
Parameters:  none. 
Returns:  nothing 
Alters: 


Initialize  the  input  device. 


Destroys: 
Description: 

See  also: 


mouseXPos  initialized  (typically  8). 

mouse  YPos  initialized  (typically  8). 

mouseData  initialized  (typically  reflects  a  released  button). 

pressFlag  initialized  (typically  set  to  $00). 

assume  a,  x,  y,  r0-rl5 

GEOS  calls  InitMouse  after  first  loading  an  input  driver.  The  input  driver  is 
expected  to  initialize  itself  and  begin  tracking  the  input  device.  An  application 
should  never  need  to  call  InitMouse. 

SlowMouse,  UpdateMouse,  SetMouse,  KeyFilter,  StartMouseMode, 
MouseUp. 
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InitProcesses 


InitProcesses  (Apple,  C64,  cns) 


process 


Function: 
Parameters: 

Returns: 

Destroys: 

Description: 


Note: 


Example: 
See  also: 


Initialize  and  install  a  process  data  structure. 

a       NUM_PROC  —  number  of  processes  in  table  (byte). 

rO  PTABLE —  pointer  to  process  data  structure  to  use  (word). 

rO  unchanged. 

a,  X,  y,  rl 

InitProcesses  installs  and  initializes  a  process  data  structure.  All  processes 
begin  as  frozen,  so  their  timers  are  not  decremented  during  vblank.  Processes  can 
be  started  individually  with  RestartProcess  after  the  caU  to  InitProcesses. 

InitProcesses  copies  the  process  data  structure  into  an  internal  area  of  memory 
hidden  from  the  application.  GEOS  maintains  the  processes  within  this  intemd 
area,  keeping  track  of  the  event  routijie  addresses,  the  timer  initialization  values 
(used  to  reload  the  timers  after  they  time-out),  the<:urrent  value  of  the  timer,  and 
the  state  of  each  process  (i.e.,  frozen,  blocked,  runable).  The  application's  copy 
of  the  process  data  structure  is  no  longer  needed  because  GEOS  remembers  this 
information  until  a  subsequent  call  to  InitProcesses. 

Although  processes  are  numbered  starting  with  zero,  NUMJPROC  should  be  die 
actual  number  of  processes  in  the  table.  To  initialize  a  process  table  with  four 
processes,  pass  a  NUMJPROC  value  of  $04.  When  refering  to  those  processes 
(i.e.,  when  calling  routines  such  as  UnblockProcess),  use  tiie  values  $00-$03. 
Do  not  call  InitProcesses  with  a  NUM  PROC  value  of  $00  or  a  NUMJPROC 
value  greater  than  MAX_PROCESSES  (the  maximum  number  of  processes 
allowable).  " 

To  disable  process  handling,  merely  freeze  all  processes  or  call  InitProcesses 
with  a  dummy  process  data  structure. 


Sleep,  RestartProcess. 
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InitRa 


InitRam  (Apple,  C64,  C128)  memory 


Function :       Table  driven  initialization  for  variable  space  and  other  memory  areas. 
Parameters:    rO      TABLE  — address  of  initialization  table  (word). 
Returns:  nothing. 
Destroys:       a,  x,y,  rO-r2L 

Description:  InitRam  uses  a  table  of  data  to  initialize  blocks  of  memory  to  preset  values.  It  is 
useful  for  setting  groups  of  variables  to  specific  values.  It  is  especially  good  at 
initializing  a  group  of  noncontiguous  variables  in  a  "two  bytes  here,  three  bytes 
there"  fashion. 

The  initialization  table  that  is  pointed  to  by  the  TABLE  parameter  is  a  data 
structure  made  up  from  the  following  repeating  pattern: 

•  word       addzBss  ;  start  address  of  this  block 

.byte       count  ;nuxnber  of  bytes  to  initialize 

•byte       bytel,  byte2fJbytGi^  ;  count  bytes  of  data 

•word       Address^.  ;  start  address  for  next  block 

The  table  is  made  of  blocks  that  follow  the  above  pattern,  count  bytes  starting  at 
address  are  initialized  with  the  next  count  bytes  in  the  table.  (A  count  value  of  $00 
is  treated  as  256.)  To  end  the  table,  use 

.word       $0000  ;end  table 

where  InitRam  expects  the  next  address  parameter. 
Note :  Do  not  use  InitRam  to  initalize  rO-r2L. 

Example: 

See  also:       FillRam,  ClearRam. 
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InltTextPrompt 


InitSprite  (Apple) 


sprite! 


Function: 
Parameters: 
Returns: 
Alters: 

Destroys: 


Initializes  all  sprites. 

nothing. 

nothing. 

offFIag  set  to  TRUE. 

noEraseSprites    set  to  $00. 

all  mouse  and  sprite  parameters  set  to  $00. 

a,  X 


Ml 


Description:   InitSprite  is  called  by  the  GEOS  Kemal  during  the  boot  and  warmstart 
sequences.  It  is  probably  not  useful  to  applications. 

See  also:        DrawSprite,  GetSpriteData,  PosSprite,  EnablSprite,  DisablSprite. 


InitTextPrompt  (Apple,  C64,  cus) 


text/keyboard 


Function: 

Parameters: 

Alters: 

Destroys: 

Description; 


See  also: 
Example: 


Initialize  sprite  #1  for  use  as  a  text  prompt. 

a       HEIGHT  —  pixel  height  for  the  prompt  (byte) 

alphaFlag  %10000011 

a,  X,  y. 

InitTextPrompt  initializes  sprite  #1  for  use  as  a  text  prompt.  The  sprite  image  is 
defined  as  a  one-pixel  wide  vertical  line  of  HEIGHT  pixth.  If  HEIGHT  is  large 
enough,  the  double-height  sprite  flags  will  be  set  as  necessary.  HEIGHT  is 
usually  taken  from  curHeight  so  that  it  reflects  the  height  of  the  current  font. 

The  text  prompt  will  adopt  the  color  of  the  nx)use  pointer. 

PromptOn,  PromptOff. 
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InputByte 


InputByte  (Apple) 


card  driver! 


Function: 

Parameters: 

Returns: 

Destroys: 
Description: 

Note: 


Example: 
See  also: 


Get  a  byte  of  input  from  the  interface  card, 
none. 


X 

y 

a,y. 


STATUS  —  card  error  code;  $00  =  no  error  (byte) 
DATA  —  single  input  byte  as  read  from  card. 


InputByte  returns  a  byte  of  data  from  the  card,  assuming  the  card  supports  two- 
way  communication.  The  input-ready  flag  may  be  checked  with  StatusCard 
prior  to  calling  InputByte. 

InputByte  must  be  called  after  an  OpenCard  and  before  a  CloseCard. 

Most  card  drivers  always  return  NO^ERROR  from  from  InputByte  due  to  a 
lack  of  memory  to  properly  handle  coinplex  error  checking. 


OutputByte,  StatusCard. 
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InsertRecord 


InsertRecord  (Apple,  C64,  cus) 


VLIR  disk 


Function:       Adds  an  empty  record  before  the  current  record  in  the  index  table,  moving  all 
subsequent  records  (including  the  current  record)  downward 


Parameters:  none 
Uses: 


Returns: 
Alters: 


Destroys: 
Description: 


Example: 
See  also: 


curDrive 
fileWrittent 

curRecord 
fileHeader 

Commodore: 

curType 

curDirHead 

dir2Headt 

dir3Headt 

Apple; 

curVBlknot 

VBMchanged^ 

numVBMBlkst 


if  FALSE,  assumes  record  just  opened  (or  updated)  and 

reads  B ANVVBM  into  memory. 

current  record  pointer 

VLIR  index  table  stored  in  this  buffer. 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing, 
current  directory  header/B  AM. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
X         error  ($00  =  no  error). 

curRecord  new  lecord  becomes  the  current  record. 

flleWritten^        set  to  TRUE  to  indicate  the  file  has  been  altered  since  last 
updated. 

fileHeader         new  record  added  to  index  table. 

^used  internally  by  GEOS  disk  routines:  explications  generally  don't  use. 

a,  y.  rOL. 

InsertRecord  attempts  to  insert  an  empty  VLIR  record  in  front  of  the  current 
record  in  the  index  table  of  an  open  VLIR  file,  moving  all  subsequent  records 
downward  in  the  record  Ust.  The  new  record  becomes  the  current  record.  A  VLIR 
file  can  have  a  maximum  of  MAX  VLIR  RECS  records.  If  adding  a  record 
will  exceed  this  value,  an  OUT^OP^RECORDS  error  is  returned.  In  the  index 
table,  the  new  record  is  marked  as  useS  but  empty. 

InsertRecord  does  not  update  the  VLIR  file  information  on  disk.  Call 
CloseRecordFile  or  UpdateRecordFile  to  update  the  file  when  done 
modifying. 


AppendRecord,  DeleteRecord. 
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interruptMain 


InterruptMain  (Apple,  C64,  cns) 

Function:  Main  Interrupt  Level  processing. 

Parameters:  none. 

Returns:  nothing. 

Destroys:  a,  x,  y,  r0-rl5 

Description:  InterruptMain  is  the  main  GEOS  Interrupt  Level  processing  loop  and  that 
means  different  things  on  different  systems. 

C64  &  C128:  InterruptMain  is  a  subset  of  the  full  Interrupt  Level  process.  InterruptMain  is 
typically  called  through  the  IntTopVec.  An  application  could  conceivably 
jsr  InterruptMain  to  "catch  up"  on  some  system  updating  if  interrupts  have 
been  disabled  for  a  considerable  period  of  time.  InterruptMain  is  not  re-entrant, 
so  it  is  important  that  interrupts  be  disabled  around  the  catch-up  calls. 

Apple:  InterruptMain  is  cuirendy  the  same  as  IrqMiddle.  It  is  best  to  use  IrqMiddle 

to  generate  software  interrupts  because  the  Apple  GEOS  InterruptMain  may 
change  in  the  future  to  more  closely  reflect  the  operation  under  the  Commodore 
environment  At  this  time,  avoid  this  jump  table  entry. 

See  also:       IrqMiddle,  MainLoop. 


internal 
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InvertLine  (Apple,  C64,  cm) 


graphics! 


Function: 
Parameters: 


Uses: 

Returns: 
Destroys: 


Description: 


Note: 


128: 


Example: 
See  also: 


Invert  the  pixels  on  a  horizontal  line. 

r3      XI  —  x-coordinate  of  leftmost  endpoint  (word). 
r4      X2  —  x-coordinate  of  rightmost  endpoint  (woid). 
rllL  Yl  —  y-coordinate  of  line  (byte). 

where  (Xl,Yl)and  (X2,Y1)  define  the  endpoints  of  the  line  to  invert. 

dispBufferOn: 

bit  7  —  invert  foreground  screen  if  set 
bit  6  —  invert  background  screen  if  set. 

nothing 

Commodore 
a,  X,  y,  r5-r8 

Applg 
a,  X,  y 

InvertLine  inverts  the  pixel  state  of  all  pixels  which  fall  on  the  horizontal  line 
whose  coordinates  are  passed  in  the  GEOS  registers.  Set  pixels  become  clear,  and 
clear  pixels  become  set. 

If  dispBufferOn  is  set  to  invert  on  the  foreground  and  the  background  screen, 
both  the  foreground  and  the  background  screen  will  get  the  inverted  foreground 
pixels.  GEOS  assumes  both  screens  contain  the  same  image. 

Under  GEOS  128,  or'ing  DOUBLE  W  into  theXi  andX2  parameters  will 
automatically  double  the  x-position  in  SD-column  mode.  Or*ing  in  ADDl  W  will 
automatically  add  1  to  a  doubled  x-position.  (Refer  to  "GEOS  128  X-posi5on  and 
Bitmap  Doubling"  in  Chapter.®  gr@  for  more  information.) 


VerticalLine,  HorizontalLine,  ImprintLine,  RecoverLine,  DrawLine. 
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InvertRectangle  (Apple,  C64,  ci28) 


graphics! 


Function: 
Parameters: 


Inverts  the  pixels  within  a  rectangular  region. 

r3  XI  —  x-coordinate  of  upper-left  (word). 

r2L  Y 1  —  y-coordinate  of  upper-left  (byte). 

r4  X2  —  x-coordinate  of  lower-right  (word). 

r2 H  Y2  —  y-coordinate  of  lower-right  (byte). 


where  (XI, Yl )  is  the  upper-left  corner  of  the  rectangular  area  and  (X2,Y2)  is  the 
lower-right  corner. 


Uses :  dispBufferOn: 

bit  7  —  invert  on  foreground  screen  if  set. 
bit  6  —  invert  on  background  screen  if  set 


Returns:  nothing 

Destroys:  Commodore 

a,  X,  y,  r5-r8,  rllH 

Applg 

a,  X,  y,  rllH 


Description:  InvertRectangle  inverts  all  the  pixels  within  the  rectangular  area  as  determined 
by  the  coordinates  of  the  upper-left  and  lower-right  comers.  All  set  pixels  become 
clear  and  clear  clear  pixels  become  set 

InvertRectangle  operates  by  calling  InvertLine  in  a  loop. 

InvertRectangle  is  handy  to  use  for  indicating  a  selected  object  (as  GEOS  does 
with  icons)  or  for  flashing  an  area  by  inverting  a  rectangle  twice,  first  inverting 
the  area  and  then  mverting  it  back  to  its  original  state. 

Note:  If  dispBufferOn  is  set  to  invert  on  the  foreground  and  the  background  screen, 

both  the  foreground  and  the  background  screen  will  get  the  inverted  foreground 
pixels.  GEOS  assumes  both  screens  contain  the  same  image. 

128:  Under  GEOS  128,  or'ing  DOUBLE  W  into  theX/  andX2  parameters  will 

automatically  double  die  x-position  in  SD-column  mode.  Or'ing  in  ADDl  W  will 
automatically  add  1  to  a  doubled  x-position.  (Refer  to  "GEOS  128  X-posi"Hon  and 
Bitmap  Doubling"  in  Chapter.®  gr@  for  more  information.) 

Example: 

See  also:       Rectangle,  ImprintRectangle,  RecoverRectangle,  FrameRectangle. 
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IrqMiddle  (Apple) 


internall 


Function:  Interrupt  Level  processing. 
Parameters:  none. 


Returns: 

Destroys: 

Description: 


Example: 
See  also: 


nothing, 
a,  X,  y 

IrqMiddle  is  the  software-interrupts  entry  into  the  Apple  GEOS  Kemal.  When 
there  is  no  hardware  interrupt  source,  GEOS  generates  software  interrups  by 
calling  IrqMiddle.  In  most  cases,  as  long  as  the  application  returns  to 
MainLoop  frequently  enough,  the  system  degradation  will  only  be  minor. 
However,  applications  which  do  massive  anaounts  of  processing  before  returning 
to  MainLoop  may  need  to  generate  software  interrupts  periodically. 


bit 
bne 
php 
sei 

jsr 
pip 


intSource 
10$ 


IrqMiddle 


; check  interrupt  source 

;do  nothing  if  hard  interrupts 

;else,  disable  interrupts 

;(just  in  case)  because  int 

;code  is  not.  re-entrant 

/software  interrupt  now! 

; restore  old  interrupt  status 


10$: 


InterruptMain. 
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IsMselnRegion  (Apple,  C64,  ci28) 

Function: 
Parameters: 


Returns: 

Destroys: 
Description: 


Note: 


NewIsMselnRegion : 


5$: 
10$: 


Ida 

mouseYPos 

cmp 

r2L 

bit 

10$ 

cmp 

r2H 

bgt 

10$ 

php 

sei 

cmpW 

mouseXPos, r3 

bit 

5$ 

cmpW 

mouseXPos, r4 

bgt 

5$ 

pip 

Ida 

#TRUE 

rts 

pip 

Ida 

#FALSE 

rts 

mouse 


;get  mouse  y-position 

/compare  to  top  edge 

/branch  if  outside 

/compare  to  bottom  edge 

/branch  if  outside 

/disable  interrupts  around  x  check 

/so  it  doesn't  change  while  we're  looking 

/compare  mousex  with  left  edge 

/branch  if  outside 

/compare  mousex  with  right  edge 

/branch  if  outside 

/  (restore  interrupts  before  se.tting  st  reg) 

/return  inside  region  statys 

/exit 

/ (restore  interrupts  before  setting  st  reg) 

/return  outside  region  status 
/exit 


Checks  to  see  if  the  mouse  is  within  a  specified  rectangular  region  of  the  screen. 

r3       XI  —  x-coordinate  of  upper-left  (word), 
r2L     Yl  —  y-coordinate  of  upper-left  (byte). 
r4       X2  —  x-c(X)rdinate  of  lower-right  (word). 
r2H    Y2  —  y-coordinate  of  lower-right  (byte). 

where  (XI, Yl )  is  the  upper-left  corner  of  the  rectangle  and  (X2,Y2)  is  the  lower- 
right  corner. 

a       TRUE  if  in  region,  FALSE  if  not  in  region. 

st      result  of  loading  TRUE  or  FALSE  into  the  a  register. 

nothing. 

IsMselnRegion  tests  the  position  of  the  mouse  against  the  boundaries  of  a 
rectangular  region  (passed  in  the  same  GEOS  registers  as  the  Rectangle 
routine).  It  returns  TRUE  if  the  mouse  is  within  the  region  (inclusive)  and 
FALSE  if  the  mouse  is  outside  the  region.  Because  the  st  register  reflects  the 
result  of  loading  TRUE  or  FALSE  into  the  accumulator,  the  call  can  be 
followed  by  a  branch  instruction  that  tests  the  result,  such  as: 

beq  InRegion  /branch  if  mouse  was  in  region 

-or- 

bne  Not InRegion    /branch  if  mouse  not  in  region 

Interrupts  should  always  be  disabled  around  a  call  to  IsMselnRegion. If  the 
php-sei-pip  method  is  used,  be  aware  that  the  pip  will  reset  the  st  flags.  If  this 
is  troublesome,  it  may  warrant  creating  a  new  version  of  IsMselnRegion  that 
does  its  own  interrupt  disable  and  leaves  the  values  in  the  st  register  intact: 
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Example: 


LoadW 

LoadW 

LoadW 

LoadW 

php 

sei 

jsr 

pip 

tax 

beq 


r3, #windowXl 
r2L,#windowYl 
r4,#windowX2 
r2H, #windowY2 


IsMselnRegion 


;get  coordinates  of  window's  rectangle 

/disable  interrupts  around  region  check 
/check  for  mouse  inside  region 


;set  status  flags  that  pip  killed 
MouseOutsideWindow    /branch  if  outside  window  area 
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JsrToAux  (Apple  only) 


utility 


Function: 
Parameters: 

Returns: 

Destroys: 

Description: 


Example: 
See  also: 


jsr*s  to  a  subroutine  in  auxiliary  memory.  Returns  to  main  memory. 

a  [AUXADDR  —  low  byte  of  subroutine  to  call  in  aux.  memory. 
X       ]  AUXADDR  —  high  byte  of  subroutine  to  call  in  aux  memory. 

where  AUXADDR  is  the  address  of  a  subroutine  to  call  in  aux.  memory 

depends  on  the  subroutine. 

depends  on  the  subroutine. 

JsrToAux  performs  a  jsr  to  a  subroutine  in  application  auxiliary  memory. 
GEOS  will  first  switch  application  aux  in  and  application  main  out,  then  simulate 
a  jsr  to  the  address  passed  in  x  and  a.  When  the  aux  memory  subroutine  returns, 
control  will  resume  in  main  memory.  JsrToAux  does  not  check  for  a  null 
($0000)  address  like  CallRoutine. 


CallRoutine 
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IKeyFilter  (Apple) 


input  driver 


Function: 

Parameters: 

Returns: 

Alters: 


Uses: 

Destroys: 

Description: 


Note: 


Pre-processes  keyboard  input  for  filtering  out  special  characters,  translating 
others,  and  updating  the  mouse  variables  when  positioning  keys  are  pressed. 


a 


a 


KEY  —  key  as  scanned  from  keyboard  circuitry, 
translated  character  or  NULL  if  filtering  out 


mouseXPos 

mouseYPos 

mouseData 

pressFIag 

inputData 


mouse  x-position. 
mouse  y-position. 
state  of  mouse  button. 

MOUSE^BIT  and  INPUT^^BIT  set  appropriately, 
depends  on  device.  " 


OPEN^APPLE  read-only  hardware  location;  negative  if  open-apple  pressed 
assume  x,  y 

The  Apple  GEOS  keyboard  scanning  routine  calls  KeyFilter  at  Interrupt  Level 
whenever  a  keypress  is  detected.  This  allows  the  input  driver  to  translate  certain 
keypresses  into  mouse  movements.  KeyFilter  has  first  dibs  on  any  incoming 
keypress. 

A  typical  KeyFilter  routine  will  compare  the  KEY  parameter  against  a  table  of 
specific  keypresses.  If  there  is  no  match,  then  KeyFilter  returns  without  altering 
the  KEY  ccxie.  If  there  is  a  match,  KeyFilter  updates  the  mouse  variables 
appropriately  and  returns  a  KEY  value  of  NULL.  Apple  GEOS  will  ignore  the 
null-key,  never  placing  it  in  the  keyboard  input  queue. 

IfKEY  is  already  NULL  when  KeyFilter  is  called,  then  the  keypress  has 
already  been  filtered  out  by  some  other  prior  filter  and  should  be  ignored. 

An  application  should  not  call  KeyFilter  direcdy;  Apple  GEOS  will  call  it 
automatically  at  Interrupt  Level. 

The  KEY  parameter  is  not  a  GEOS  key  value.  It  comes  almost  direcdy  from  the 
Apple  hardware  register  KEYBD^DATA.  The  only  difference  is  tiiat  the  high- 
bit  is  set  to  represent  the  state  oflhe  closed-apple  key.  If  bit  7  is  set,  then  the 
closed-apple  key  is  pressed.  To  detect  die  state  of  the  open-apple  key: 


bit 
bmi 


OPEN_APPLE 
OpenPressed 


/check  open  apple  key  status 
/branch  if  pressed 


See  also:  AuxDKeyFilter. 
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LdApplic  (Apple,  C64,  C128) 


mid-level  disk  I 


Function: 
Parameters: 


Uses: 


Returns: 
Passes: 

Alters: 

Destroys: 
Description: 


Load  and  (optionally)  run  a  GEOS  application,  passing  it  the  standard  application 
startup  flags  as  if  was  launched  from  the  deskTop. 

r9        DIRENTRY  —  pointer  to  directory  entry  of  file,  usually  points  to 

dirEntryBuf  (Apple  GEOS:  must  be  in  main  memory)  (word). 
rOL  LOAD.OPT: 

bitO:  0  load  at  address  specified  in  file  header;  application  will  be 
started  automatic^y 

load  at  address  in  r7;  application  will  not  be  started 
automatically, 
not  passing  a  data  file. 

r2  and  r3  contain  pointers  to  disk  and  data  file  names, 
not  printing  data  file, 
printing  data  file;  application  should  print  file  and  exit 
r7        LOAD_ADDR  —  optional  load  address,  only  used  if  bit  0  of 

LO AD  jOPT  is  set  (word). 
r2        DATA^DISK— only  validif  bit7orbit6ofL<9i4D_0/Tis  setrpointer 
to  name  of  the  disk  that  contains  the  data  file,  usually  a  pointer  to  one  of 
the  DrxCurDkNm  buffers  (word). 
r3        DATA^FELE  —  only  valid  if  bit  7  or  bit  6  of  LOAD  jOPT  is  set:  pointer 
to  name  of  the  data  file  (word). 


bit  7: 
bit  6: 


1 

0 
1 
0 


curDrive 

Commodore: 
curType 

Applg: 
RWbank 


GEOS  64  V  1.3  and  later:  for  detecting  REU  shadowing. 


destination  bank  (MAIN  or  AUX);  set  to  MAIN  when 
loading  an  application. 


only  returns  if  alternate  load  address  or  disk  error. 
X         error  ($00  =  no  error). 

usually  doesn't  return,  but  warmstarts  GEOS  and  passes  the  following: 
rO        as  originally  passed  to  LdApplic. 
r2        as  originally  passed  to  LdApplic  (use  dataDiskName). 
r3        as  originally  passed  to  LdApplic.(use  dataFileName). 

GEOS  brought  to  a  warmstart  state. 

dataDiskName    contains  name  of  data  disk  if  bit  7  of  rO  is  set. 
dataFileName     contains  name  of  data  file  if  bit  6  of  rO  is  set 

a,  X,  y,  r0-rl5. 

LdApplic  is  a  mid-level  application  loading  routine  called  by  the  higher  level 
GetFile.  Given  a  directory  entry  of  a  GEOS  application  file,  LdApplic  will 
attempt  load  it  into  memory  and  optionally  run  it.  LdApplic  calls  LdFile  to  load 
the  application  into  memory:  a  sequential  file  is  loaded  entirely  into  memory  but 
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only  record  zero  of  a  VLIR  file  is  loaded.  Based  on  the  status  of  bit  0  of 
LOADJDPT,  optionally  runs  the  application  by  calling  it  through  StartAppl. 

Most  applications  will  not  call  LdApplic  directly  but  will  go  indirectly  through 
GetFile. 

Note:  Only  in  extremely  odd  cases  will  an  alternate  load  address  be  specified  for  an 

application.  Loading  an  application  at  another  location  is  not  particularly  useful 
because  it  will  most  likely  not  run  at  an  address  other  than  its  specifiec  load 
address.  When  LdApplic  returns  to  the  caller,  it  does  so  before  calling 
StartAppl  to  wamistart  GEOS. 

Apple:  Applications  are  designed  to  load  and  run  in  main  memory.  Ensure  that  RWbank 

contains  MAIN  before  calling  LdApplic. 

Example: 

See  also:        GetFile,  LdDeskAcc,  LdDeskAcc,  StartAppl. 


J 
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LdPeskAcC  (Apple,  C64,  C128) 


mid-level  disk 


Function:  Load  and  run  a  .GEOS  desk  accessory 
Parameters:  r9 

rlOL 


DIRENTRY  —  pointer  to  directory  entry  of  file,  usually  points  to 
dirEntryBuf  (word). 

RECVR^OPTS  —  no  longer  used;  set  to  $00  (sec  below  for  explanation 
(byte). 


Uses: 


curDrive 

Cpmrnodpr?; 
curType 

Apple; 
RWbank 


GEOS  64  vl.3  and  later:  for  detecting  REU  shadowing. 


destination  bank  (MAIN  or  AUX);  set  to  MAIN  when 
loading  a  desk  accessory. 


Returns: 


Passes: 


Alters: 


returns  when  desk  accessory  exits  with  a  call  to  RstrAppl. 
X         error  ($00  =  no  error). 

warmstarts  GEOS  and  passes  the  following  to  the  desk  accessory: 

rlOL     as  originally  passed  to  LdDeskAcc  (should  be  $(X);  see  below). 

nothing  direcdy;  desk  accessory  may  alter  some  buffers  that  arc  not  saved 


Destroys:       a,  x,  y,  r0-rl5. 


Description: 


Note: 


LdDeskAcc  is  a  mid-level  desk  accessory  loading  routine  called  by  the  higher 
level  GetFile.  Given  a  directory  entry  of  a  GEOS  desk  accessory  file, 
LdDeskAcc  will  attempt  load  it  into  memory  and  run  it.  When  the  user  closes 
the  desk  accessory,  control  returns  to  die  calling  application. 

LdDeskAcc  first  loads  in  the  desk  accessory's  file  header  to  get  the  start  and 
ending  load  address.  Under  GEOS  64  and  Apple  GEOS,  it  will  then  save  out  the 
area  of  memory  between  these  two  addresses  to  a  file  on  the  current  disk  named 
SWAP  FILE.  The  GEOS  128  version  saves  this  area  to  the  24K  desk 
accessory  swap  area  in  back  RAM.  Desk  accessories  larger  than  24K  cannot  be 
used  under  GEOS  128  (to  date,  there  are  none);  a  BFR^OVERFLOW  error  is 
returned. 

After  saving  the  overlay  area,  the  dialog  box  and  desk  accessory  save-variables 
are  copied  to  a  special  area  of  memory,  the  current  stack  pointer  is  remembered, 
and  the  desk  accessory  is  loaded  and  executed.  When  the  desk  accessory  calls 
RstrAppl  to  return  to  the  application,  this  whole  process  is  reversed  to  return  the 
system  to  a  state  similar  to  the  one  it  was  in  before  the  desk  accessory  was  called. 
The  SWAP  FILE  file  is  deleted. 

Most  applications  will  not  call  LdDeskAcc  directly,  but  will  go  indirectly 
tiirough  GetFile. 

The  RECVRjOPTS  flag  originally  carried  die  following  significance: 
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C64  : 

Apple: 

Example: 
See  also: 


bit  7:   1    force  desk  acxessory  to  save  foreground  screen  area  and  restore  it  on  return  to 
application. 

0    not  necessary  for  desk  accessory  to  save  foreground. 
Commodore  only: 

bit  6:    1    force  desk  accessory  to  save  color  memory  and  restore  it  on  return  to 
application. 

0    notnecessary  for  desk  accessory  to  save  color  memory. 

However,  it  was  found  that  the  extra  code  necessary  to  make  desk  accessories 
save  the  foreground  screen  and  color  memory  provided  no  real  benefit  because 
this  context  save  can  just  as  easily  be  accomplished  finom  within  the  application 
itself.  The  RECVRjOPTS  flag  is  set  to  $00  by  all  Berkeley  Softworks 
applications,  and  desk  accessories  can  safely  assume  that  this  will  always  be  the 
case.  (In  fact,  future  versions  of  GEOS  may  force  rlOH  to  $00  before  calling 
desk  accessories  just  to  enforce  this  standard!) 

The  application  should  always  set  rlOH  to  $00  and  bear  the  burden  of  saving  and 
restoring  the  foreground  screen  and  the  color  memory.  (Color  memory  only 
applicable  to  GEOS  64  and  GEOS  128  in  40-column  mode.) 

GEOS  versions  1.3  and  above  have  a  new  GEOS  file  type  called 
TEMPORARY.  When  the  deskTop  first  opens  a  disk,  it  deletes  all  files  of  this 
type.  The  SWAP  FILE  is  a  TEMPORARY  file. 

Desk  accessories  are  designed  to  load  into  main  memory.  Ensure  that  RWbank 
contains  MAIN  before  calling  LdApplic. 


GetFile,  LdApplic,  LdFile,  RstrAppI,  InitForDialog,  RstrFrmDialog, 
WarmStart. 
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LdFile  (Apple,  C64,  C128) 


mid-level  disk! 


Function: 
Parameters: 

Uses: 


bitO: 


Given  a  directory  entry,  loads  a  sequential  file  or  record  zero  of  a  VLIR  record. 

r9        DIRENTRY  —  pointer  to  directory  entry  of  file,  usually  points  to 
dirEntryBuf  (Apple  GEOS:  must  be  in  main  memory)  (word). 

curDrive 

Commodore! 
curType 

Applg; 
RWbank 
loadOptt 
0 
1 

loadAddr^ 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing. 


destination  bank  (MAE^  or  AUX). 
load  option: 

-load  at  address  specified  in  file  header, 
-load  at  address  in  loadAddr. 
alternate  load  address. 


Returns: 
Alters: 


^former  local  variable;  applications  will  generally  not  use  outside  of  this  context. 

X         error  ($00  =  no  error). 

r7        pointer  to  last  byte  read  into  BUFFER  plus  one. 


fileHeader 


Cpmmodprp; 
fileTrScTab 


contains  256-byte  GEOS  file  header.  (This  is  a  512-byte 
buffer  in  Apple  GEOS,  although  only  256  bytes  are  used  in 
the  GEOS  file  header  for  compatibility). 


track/secto^  of  header  in  first  two  bytes  of  this  table 
(fileTrScTab+O  and  fileTrScTab+l);  As  the  file  is 
loaded,  the  track/sector  pointer  to  each  block  is  added  to  die 
file  track/sector  table  starting  at  fiIeTrScTab+2  and 
fiIeTrScTab+3. 


Destroys: 


Apple: 

INDEXBLOCKBUF 


Apple; 

a,  y,  rl,  r4,  r7. 


index  block  for  file  if  sequential  or  record  0  if  VLIR 
(in  auxiliary  memory;  see  ReadFile  for  information 
on  accessing  this  buffer). 


Description:   LdFile  is  a  mid-level  file  handling  routine  called  by  die  higher  level  GetFile. 

Given  a  directory  entry  of  a  sequential  file,  LdFile  will  load  it  into  memory. 
Given  die  directory  entry  of  a  VLIR  file,  LdFile  will  load  its  record  zero  into 
memory. 

Most  applications  will  not  call  LdFile  directiy  but  will  access  this  routine 
indirectiy  tiirough  GetFile. 
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LdFiie 


C64  &C128:  All  versions  of  LdFiie  to  date  under  Commodore  GEOS  are  unusable  because 
the  load  variables  that  are  global  under  Apple  GEOS  GoadOpt  and  loadAddr) 
are  local  to  the  Kemal  and  inaccessible  to  applications.  Fortunately  this  is  not  a 
problem  because  applications  can  always  go  through  GetFile  to  achieve  the  same 
effect 

Example: 

See  also:       GetFile,  LdApplic,  LdDeskAcc,  ToB ASIC. 


^ 
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LoadAuxSet 


LoadAuxSet  (Apple) 


text 


Function: 
Parameters: 
Returns: 
Alters: 


Begin  using  a  new  font  that  resides  in  ausiliaiy  memory. 
rO      FONTPTR  —  aux.  memory  address  of  font  header 
rO  unchanged 


curHeight 

baselineOffset 

cardDataPntr 

curlndexTable 

curSetWidth 


height  of  font 

number  of  pixels  ftom  top  of  font  to  baseline, 
pointer  to  current  font  image  data, 
pointer  to  current  font  index  table, 
pixel  width  of  font  bitstream  in  bytes. 


Destroys:  a,  x,  y 
Description: 


Example: 
See  also: 


LoadAuxSet  operates  cxacdy  like  LoadCharSet  except  that  it  lets  the  font  data 
reside  in  auxiliaiy  memory. 


LoadCharSet,  UseSystemFont. 
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LoadCharSet 


LoadCharSet  (Apple,  C64,  cns) 


text 


Function: 
Parameters: 

Returns: 
Alters: 


Begin  using  a  new  font. 


Destroys: 
Description: 

Apple: 
Example: 
See  also: 


rO 


rO 


FONTPTR  —  address  of  font  header.  If  Apple,  address  must  be  in  main 
memory  (word). 


curHeight 

baselineOffset 

cardDataPntr 

curlndexTable 

curSetWidth 

a.y. 


unchanged 
height  of  font 

number  of  pixels  fiiom  top  of  font  to  baseline, 
pointer  to  current  font  image  data, 
pointer  to  current  font  index  table, 
pixel  width  of  font  bitstrcam  in  bytes. 


LoadCharSet  uses  the  data  in  the  character  set  data  structure  to  initalize  the  font 
variables  for  the  font  pointed  at  by  the  FONTPTR  parameter. 

If  the  font  data  is  stored  in  auxiliary  memory,  LoadAuxSet  must  be  used. 


LoadAuxSet,  UseSystemFont. 
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MainLoop 


MainLoop  (Apple,  C64,  cus) 


internal  I 


Function:       Direct  entiy  into  the  GEOS  MainLoop.. 
Parameters:  nothing. 
Returns:  n/a 
Destroys:  n/a 

Description:  Although  the  term  "MainLoop"  usually  refers  to  GEOS  MainLoop  Level 
processing,  it  also  represents  an  entry  in  the  GEOS  jump  table.  By  performing  a 
jmp  MainLoop,  the  application  would  be  returning  to  the  top  of  the  MainLoop 
Level  without  letting  it  run  through  its  normal  course  of  events.  The  application  is 
expected  to  return  to  MainLoop  Level  with  an  rts,  not  with  a  call  to  MainLoop. 
Hence,  this  jump  table  entry  is  not  terribly  useful  to  applications  and  is  primarily 
used  internally  by  GEOS. 

The  MainLoop  jump  table  entry  is  perhaps  useful  when  debugging.  The  system 
could,  conceivably,  be  returned  to  a  "known  state"  by  resetting  the  stack  pointer 
and  executing  a  jmp  MainLoop.  Of  course,  there  is  no  guarantee  that  this  will 
work. 


Example: 


See  also: 


Idx     t$ff  ; reset  stack  pointer 

txs 

jmp    Mainloop  ;try  to  get  back  to  normal.., 

InterruptMain,  Firstlnit. 
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MakeSubDIr 


MakeSubPir  (Apple) 


high-level  disk 


Function: 
Parameters: 


Creates  a  subdirectory  within  the  current  directory. 


rO 


DIRNAME  —  pointer  to  null-terminated  name  for  directory,  maximum 
of  16-characters  including  the  null  terminator  (word). 
rlOL     DIRPAGE  —  directory  page  to  begin  searching  for  free  slot;  each 
directory  page  holds  eight  files  and  corresponds  to  one  notepad  page  on 
the  GEOS  deskTop.  The  first  page  is  page  one  (byte). 


Uses: 
Returns: 

Alters: 

Destroys: 
Description: 


curDrive 
curKBlkno 


current  directory. 


X         error  ($00  =  no  error). 

rlOL    directory  page  actually  used 

r6        block  number  of  key  block  of  new  directory. 


dirEntryBuf 
diskBlkBuf 

a,  y,  r3-r8. 


contains  newly-built  directory  entry, 
contains  directory  header  just  written. 


MakeSubDir  creates  an  empty  subdirectory  in  the  current  directory.  Care  must 
be  taken  not  to  create  two  subdirectories  with  the  same  name  as  MakeSubDir 
does  not  prevent  this  from  happening. 

MakeSubDir  first  calls  SetNextFree  to  allocate  the  subdirectory's  key  block 
then  calls  SetGDirEntry  to  build  its  directory  entry,  adding  it  to  the  current 
directory.  MakeSubDir  then  builds  a  directory  header  in  diskBlkBuf  and 
writes  it  out  to  the  newly-allocated  key  block. 

MakeSubDir  Hushes  the  VBM  cache. 

€64  &  C128:  Comnxxiore  GEOS  does  not  support  a  hierarchical  file  system. 

Example: 

See  also:     SetGDirEntry,  DeleteDir. 
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MouseOff 


MoUSeOff  (Apple,  C64,  C128) 


mouse/spritel 


Function: 
Parameters: 
Returns: 
Modifies: 

Destroys: 
Description: 


Example: 
See  also: 


Temporarily  disables  the  mouse  pointer  and  GEOS  mouse  tracking, 
nothing. 


nothing. 

mobenble 
mouseOn 

a 


sprite  #0  bit  cleared  by  DisablSprite. 
clears  the  MOUSEON  BIT. 


MouseOff  temporarily  disables  the  mouse  cursor  and  GEOS  mouse  tracking  by 
clearing  the  proper  bit  in  mouseOn  and  calling  DisablSprite.  Applications  can 
call  MouseOff  temporarily  disable  the  mouse.  The  mouse  can  be  reenabled  to  its 
previous  state  by  calling  MouseUp. 


MouseOff»  ClearMouseMode. 


CONriDCNTIAL 


174 


MouseUp 


MoUSeUp  (Apple,  C64,  C128) 


mouse/spritel 


Function: 
Parameters: 
Returns: 
Modifies: 

Destroys: 
Description: 

Example: 
See  also: 


Reenables  the  mouse  pointer  and  GEOS  mouse  tracking. 

nothing. 

nothing. 


mobenble 
mouseOn 

a 


sets  enable  bit  for  sprite  #0 
sets  the  MOUSEON  BIT. 


MouseUp  reenables  the  mouse  cursor  and  GEOS  mouse  tracking  after  a  call  to 
MouseOff  by  setting  the  proper  bits  in  mouseOn  and  mobenble. 
StartMouseMode  calls  this  routine. 


MouseOff,  StartMouseMode. 
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MoveAuxData  (Apple) 


memoryl 


Function: 
Parameters: 


Special  version  of  MoveData  that  will  move  data  within  either  main  or  auxiliary 
memory  (or  from  one  bank  to  the  other). 


rO 
rl 
r2 
a 


SOURCE  —  address  of  source  block  in  application  memory  (word). 
DEST  —  address  of  destination  block  in  application  memory  (word). 
COUNT  —  number  of  bytes  to  move,  0  -  32K  (word). 
BANKS  —  which  banks  to  use,  based  on  the  following  bit  fields: 
b7  b6  Description 


0 

0 

SOURCE  and  DEST  both  in  main  memory. 

0 

1 

SOURCE  in  main  memory.  DEST  in  auxiliary  memory. 

1 

0 

SOURCE  in  auxiliary  memory,  DEST  in  main  memory. 

1 

1 

SOURCE  and  DEST  both  in  auxiliary  memory. 

Returns:  rO,  rl,  r2  unchanged. 
Destroys:       a,  x,  y 


Description: 


Note: 

Example: 
See  also: 


MoveAuxData  (formerly  Apple  MoveBData)  is  a  block  move  routine  that 
allows  data  to  be  moved  in  either  main  memory,  auxiliary  memory,  or  between 
main  and  auxiliary.  Like  MoveData,  it  will  move  up  to  32K  (32,768  bytes)  from 
one  area  of  memory  to  another  and  the  source  and  destination  blocks  can  overlap. 
The  move  is  actually  a  copy  in  die  sense  that  the  source  data  remains  unalter^ 
unless  the  destination  area  is  in  the  same  bank  and  overlaps  the  source. 

MoveAuxData  is  especially  useful  for  copying  data  from  main  memory  to 

auxiliary  memory  or  from  auxiliary  memory  to  main  memory. 

« 

MoveAuxData  should  only  be  used  to  move  data  within  the  application  space  in 
main  and  auxiliary  memory.  This  area  lies  in  the  48K  block  affected  by  RAMRD 
andRAMWRT. 


MoveData,  MoveBData,  SwapMainAndAux. 


MovaAuxDota 


MOVeBData  (CnS)   memory 


Function:       Special  version  of  MoveData  that  will  move  data  within  either  front  RAM  or 
back  RAM  (or  from  one  bank  to  the  other). 

Parameters:    rO  SOURCE  —  address  of  source  block  in  application  memory  (word). 

r  1  DEST — address  of  destination  block  in  application  memory  (word). 

r2  COUNT  —  number  of  bytes  to  move  (word). 

r3L  SRCB ANK  —  source  bank:  0  =  back  RAM;  1  =  front  RAM  (byte). 

r3H  DSTBANK  —  destination  bank:  0  =  back  RAM;  1  =  front  RAM  (byte). 


Returns:        r0-r3  unchanged. 
Destroys:       a,  x,  y 

Description:  MoveBData  is  a  block  move  routine  that  allows  data  to  be  moved  in  either  front 
RAM,  back  RAM,  or  between  front  and  back  (bank  1,  the  front  bank,  is  the 
normal  GEOS  application  area).  If  the  SOURCE  and  DEST  areas  are  in  the  same 
bank  and  overlap,  DEST.  must  be  less  than  SOURCE. 


MoveBData  is  especially  useful  for  copying  data  from  front  RAM  to  back  RAM 
or  from  back  RAM  to  front  RAM. 


MoveBData  uses  the  DoBOp  primitive  by  calling  it  with  a  MODE  parameter  of 
$00. 

Note:  MoveBData  should  only  be  used  to  move  data  within  the  designated  application 

areas  of  memory.  MoveBData  is  signifcantiy  slower  than  MoveData  and 
should  be  avoided  if  the  move  will  occur  entirely  within  front  RAM. 

Example: 


See  also: 


MoveData,  MoveAuxData,  SwapBData,  VerifyBData,  DoBOp. 


MoveData 


MovePata^  i  MovePata  (Apple,  C64,  ci28) 


memory  I 


Function: 
Parameters: 


Returns: 

Destroys: 

Description: 


64  &  128: 


64: 


128: 


Apple: 


Moves  a  block  data  from  one  area  to  another 
Normal: 

rO  SOURCE  —  address  of  source  block  (word), 
r  1  DEST — address  of  destination  block  (word). 
r2      COUNT  —  number  of  bytes  to  move  (word). 

Inline: 

data  appears  immediately  after  the  jsr  i  MoveData 
.word  SOURCE 
.word  DEST 
.word  COUNT 

rO,  rl,  r2  unchanged. 

a,y 

MoveData  will  move  data  from  one  area  of  memory  to  another.  The  source  and 
destination  blocks  can  overlap  in  either  direction,  which  makes  this  routine  ideal 
for  scrolling,  insertion  sorts,  and  odier  applications  that  need  to  move  arbitrarily 
large  areas  of  memory  around.  The  move  is  actually  a  copy  in  the  sense  that  the 
source  data  remains  unaltered  unless  the  destination  area  overlaps  it 

If  the  DMA  MoveData  option  in  the  Configure  program  is  enabled  (GEOS  vl.3 
and  later),  MoveData  will  use  part  of  bank  0  of  the  installed  RAM-expansion 
unit  for  an  ultrafast  move  operation.  An  application  that  calls  MoveData  in  the 
normal  manner  will  automatically  take  advantage  of  this  selection.  An  application 
that  relies  upon  a  slower  MoveData  (for  timing  or  other  reasons)  can  disable  the 
DMA-move  by  temporarily  clearing  bit  7  of  sysRAMFlg.  This  bit  can  also  be 
used  to  read  the  status  of  the  DMA-move  configuration. 

Due  to  insufficent  error  checking  in  GEOS,  do  not  attempt  to  move  more  than 
30,976  ($7900)  bytes  at  one  time  when  the  DMA-move  option  is  enabled.  Break 
the  move  up  into  multiple  calls  to  MoveData. 

Due  to  insufficent  error  checking  in  GEOS,  do  not  attempt  to  move  more  than 
14,592  ($3900)  bytes  at  one  time  when  the  DMA-move  option  is  enabled.  Break 
the  move  up  into  multiple  calls  to  MoveData.  MoveData  should  only  be  used 
to  move  data  within  the  standard  front  RAM  application  space.  Use  MoveBData 
to  move  memory  witiiin  back  RAM  or  between  front  RAM  and  back  RAM. 
Because  the  RAM-expansion  unit  DMA  follows  the  VIC  chip  bank  select,  an 
application  that  is  displaying  a  40-column  screen  ft'om  back  RAM  must  either 
disable  DMA-moves  or  temporarily  switch  die  VIC  chip  to  front  RAM  before  the 
MoveData  call. 

MoveData  should  only  be  used  to  move  data  within  application  main  memory. 
See  MoveAuxData  for  moving  data  within  aux  main  memory  or  between 
memory  banks. 


Note: 


Do  not  use  MoveData  on  rOHr6. 
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MoveData 


Example: 

See  also:       MoveAuxData,  MoveBData,  CopyString. 
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NewBltClip 


NewBitClip  (Apple) 


graphics 


Function: 
Parameters: 


A  special  version  of  BitmapCIip  which  allows  bitmaps  of  pixel-widths  and 
pixel-coordinate  x-positioning. 


Uses: 

Returns: 

Destroys: 

Description: 


Note: 


Example: 
See  also: 


rO 

r3 

rlH 

r2 

rlL 

rllL 

rllH 


rl2 


DATA  —  pointer  to  the  compacted  bitmap  data  (word). 
X  —  x-position  in  pixels  (word). 
Y  —  y-coordinate  (byte). 

W_PWE)TH  —  width  in  pixels  of  clipping  window  (word), 
W_HEIGHT —  height  in  pixels  of  clipping  window  (byte). 
DXl  —  delta-xl:  offset  of  left  edge  of  clipping  window  in  bytes  from  left 
edge  of  full  bitmap  (byte). 

DX2  —  delta-x2:  offset  of  right  edge  of  clipping  window  in  cards  from 
right  edge  of  full  bitmap  (byte).  Right  pixel-edge  of  clipping  window 
rounded  upward  to  the  next  card  boundary. 

DYl  —  delta-y  1:  offset  of  top  edge  of  clipping  window  in  pixels  from  top 
edge  of  full  bitmap  (word). 


where  the  upper-left  corner  of  the  clipped  bitmap  (the  window)  is  placed  at 
(X,Y).  The  lower-right  corner  is  at  (X-^WJ'WIDTH,  Y-^WJJEIGHT). 

dispBufferOn: 

bit?  — write  to  foreground  screen  if  set 
bit  6  —  write  to  background  screen  if  set 

nothing. 

a,  X,  y,  r0-rl2 

e 

NewBitClip  is  an  enhanced  version  of  BitmapCIip  which  allows  the  left  edge 
of  the  bitmap  to  be  placed  on  a  pixel  boundary  and  the  bitmap  to  have  a  pixel- 
sized  width.  It  is  odierwise  identical  to  BitmapCIip. 

No  checks  are  made  to  determine  if  the  data,  dimensions,  or  positions  are  valid. 
Be  careful  to  pass  accurate  values. 

Pay  special  attention  to  the  fact  that  DXl,  and  DX2  are  still  specified  in  cards 
(groups  of  eight  pixels  horizontally),  not  in  individual  pixels. 

Do  not  pass  a  value  of  $00  for  either  the  W^PWIDTH  or  W^HEIGHT 
parameters. 

DOUBLE  B  can  be  or'ed  into  the  W^WIDTH  paramter  to  double  the  bitmap 
width  andlNAUX^B  can  be  or'ed  into  the  X  parameter  to  specify  auxiliary 
memory.  For  morelnformation,  refer  to  "Apple  GEOS  Bitmap  Doubling  and 
Aux-memory  Bitmaps"  in  chapter  @gn@. 


NewBitOtherCIip,  BitmapCIip,  BitmapUp,  BitOtherClip. 
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NewBitOtherClip 


NewBitOtherClip  (Apple) 


graphics! 


Function: 


Parameters: 


Uses: 


Returns: 


Special  version  of  NewBitCIip  that  allows  the  compacted  bitmap  data  to  come 
from  a  source  other  than  memory  (e.g.,  from  disk). 

r 0      BUFFER  —  pointer  to  a  1 34-byte  buffer  area  (word). 
r3      X  —  x-position  in  pixels  (word). 
rlH    Y  —  y-coordinate  (byte). 

r2      W^PWIDTH  —  width  in  pixels  of  clipping  window  (word). 

rlL    W^HEIGHT  —  height  in  pixels  of  clipping  window  (byte). 

rllL  DXl  —  delta-xl:  offset  of  left  edge  of  clipping  window  in  bytes  from  left 

edge  of  full  bitmap  (byte). 
rllH  DX2  —  delta-x2:  offset  of  right  edge  of  clipping  window  in  cards  from 

right  edge  of  full  bitmap  (byte).  Right  pixel-edge  of  clipping  window 

rounded  upward  to  the  next  card  boundary, 
r  1 2    D Y 1  —  delta-y  1 :  offset  of  top  edge  of  clipping  window  in  pixels  from  top 

edge  of  full  bitmap  (word). 
rl3    APPINPUT  —  pointer  to  application-defined  input  routine.  Called  each 

time  a  byte  from  a  compacted  bitmap  is  needed;  data  byte  is  returned  in  the 

a-register. 

rl4  SYNC  —  pointer  to  synchronization  routine.  Called  after  each  bitmap 
packet  is  decompressed.  Due  to  improvements  in  NewBitOtherClip, 
this  routine  need  only  consist  of  reloading  rO  with  the  BUFFER  address. 

where  the  upper-left  corner  of  the  clipped  bitmap  (the  window)  is  placed  at 
PC,Y).  The  lower-right  corner  is  at  (X^WJ'WIDTH,  Y+WJIEIGHT). 

dispBufferOn: 

bit?  — write  to  foreground  screen  if  set. 
bit  6  —  write  to  background  screen  if  set 

nothing. 


Destroys:       a,  x,  y,  r0-rl2,  and  the  134-byte  buffer  pased  through  rO. 


Description: 


Sometimes  the  application  will  need  to  display  a  large  bitmap  but  cannot  afford  to 
store  the  entire  bitmapped  object  in  memory.  NewBitOtherClip  allows  the 
application  to  specify  an  input  routine  (APPINPUT)  thai  returns  the  next  byte  of  a 
compacted  bitmap  each  time  it  is  called 

APPINPUT  must  preserve  r0-rl3,  it  must  return  die  data  byte  in  die  a-register, 
and  it  is  expected  to  exit  widi  an  rts.  A  typical  APPINPUT  routine  might  save 
r0-rl3,  call  ReadByte  to  get  a  byte  from  a  disk  file,  restore  r0-rl3,  load  die 
data  byte  into  die  accumulator,  and  rts.  Note  tiiat  BitOtherCIipt  can  be  used  to 
add  another  level  of  compression  to  the  compacted  bitmap  format.  The 
APPINPUT  routine  can  decompress  die  data  into  compacted  bitmap  format  and 
pass  those  bytes  back. 

The  basic  widtii,  height,  position,  and  clipping  window  parameters  are  identical 
to  NewBitCIip.  Refer  to  the  documentation  of  that  routine  for  more 
information. 
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NewBitOtherCllp 


NewBitOtherClip  calls  the  APPINPUT  routine  until  it  has  enough  bytes  to 
form  one  bitmap  packet.  BitOtherCIip  stores  the  bytes  in  the  buffer  pointed  by 
BUFFER  and  then  uncompacts  the  data  to  the  screen.  After  the  bitmap  packet  has 
been  uncompacted,  BitOtherCIip  calls  the  SYNC  routine.  This  extra  call  is  no 
longer  particularyAiseful  and  can  merely  consist  of  reloading  rO  with  the 
BUFFER  address  and  performing  an  rts. 

Note:  DOUBLE^B  can  be  or'ed  into  the  W^WIDTH  parameter  to  double  the  bitmap 

width.  " 

Before  resetting  rO  when,  the  SYNC  routine  must  switch  in  the  alternate  zero 
page: 

SYNC: 

sta  ALTZP_ON  ;  switch  in  alt  zp 

MoveW  syncrO,rO  ; reload  rO 

sta  ALTZP_OFF  ;  switch  alt  zp  back  out 

rts  /return  from  sync 

Example: 

See  also:        BitOtherCIip,  NewBitClip»  BitmapClip,  BitmapUp,  BitOtherCIip. 
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NewBitOtheFClip  ( 


NewBitUp,  i  NewBitUp  (Apple)  graph»cs| 

Function:       A  special  version  of  BitmapUp  that  allows  bitmaps  of  pixel-widths  and  pixel- 
coordinate  x-positioning. 

Parameters:  Normal: 

rO      DATA  —  pointer  to  the  compacted  bitmap  data  (word). 

r3      X  —  x-coordinate  (word). 

rlH    Y  —  y-coordinate  (byte). 

r2      WIDTH — bitmap  width  in  pixels  (word). 

rlL    HEIGHT  —  bitmap  height  in  pixels  (byte). 

Inline: 

data  appears  immediately  after  the  jsr  i_BmapUp 

.word  DATA  pointer  to  the  compacted  bitmap  data. 

.word  X  x-coordinate. 

.byte  Y  y-coordinate. 

.word  WIDTH  bitmap  width  in  pixels. 

.byte  HEIGHT  bitmap  height  in  pixels. 


Uses:  dispBufferOn: 

bit  7  —  write  to  foreground  screen  if  set. 
bit  6  —  write  to  background  screen  if  set 


Returns:  nothing. 
Destroys:       a,  x,  y,  r0-r4 

Description:  NewBitUp  uncompacts  a  GEOS  compacted  bitmap  using  the  width  and  height 
information  and  places  it  at  the  specified  screen  position.  No  checks  are  made  to 
determine  if  the  data,  dimensions,  or  positions  are  valid,  and  bitmaps  which 
exceed  the  screen  edge  will  not  be  clipped.  Be  careful  to  pass  accurate  values. 

NewBitUp  differs  from  BitmapUp  in  that  it  allows  bitmaps  to  be  of  a  pixel- 
width  and  to  be  placed  at  any  pixel  postion  on  the  x-axis.  The  data  is  still 
compacted  in  card-size  (eight-pixel)  chunks,  but  when  placed  on  the  screen  any 
extra  pixels  (bits)  at  the  right  edge  are  ignored. 

Note:  Neitiier  die  WIDTH  nor  die  HEIGHT  parameter  should  be  $(X). 


DOUBLE  B  can  be  or'ed  into  die  WIDTH  paramter  to  double  the  bitmap  width 
and  INAUX_B  can  be  or'ed  into  the  XI  parameter  to  specify  auxiliary  memory. 
For  more  information,  refer  to  "Apple  GEOS  Bitmap  Doubling  and  Aux-memory 
Bitmaps"  in  chapter  @gr@. 

Example: 


See  also:        BitmapUp,  NewBitCIip,  NewBitOtherClip. 


NewDisk 


NewDisk  (C64,  cns) 


mid-level  disk 


Function: 
Parameters:  none 
Uses: 


Returns: 

Destroys: 

Description: 


Note: 

Apple: 
Example: 
See  also: 


Tell  the  turbo  software  that  a  new  disk  has  been  inserted  into  the  drive. 


curDrive 
curType 


drive  that  disk  is  in. 
GEOS  64  vl.3  and  later: 
memory  is  cleared). 


for  disk  shadowing  (shadow 


error  ($00  =  no  error). 


a,  y,  r0-r3. 

NewDisk  informs  the  disk  drive  turbo  software  that  a  new  disk  has  been 
inserted  into  the  drive.  It  first  calls  EnterTurbo  then  sends  an  initialize  command 
to  the  turbo  code.  If  the  disk  is  shadowed,  the  shadow  memory  is  also  cleared 

NewDisk  gets  called  automatically  when.OpenDlsk  opens  a  new  disk.  An 
application  that  does  not  deal  with  anything  but  the  low-level  disk  routines  might 
want  to  call  NewDisk  instead  of  OpenDisk  to  avoid  the  unnecessary  overhead 
associated  with  reading  the  directory  header  and  initializing  internal  file-level 
variables. 

NewDisk  has  no  effect  on  a  RAMdisk.  Also,  some  early  versions  of  the  1541 
turbo  code  leave  the  disk  in  the  drive  spinning  after  is  first  loaded.  A  call  to 
NewDisk  during  the  application's  initialization  wiU  stop  the  disk. 

Apple  GEOS  has  no  NewDisk  equivalent 


OpenDisk,  SetDevice. 
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NextRecord 


NextRecord  (Apple,  C64,  cns) 


VLIR  disk 


Function: 
Parameters: 
Uses: 
Returns: 


Alters: 

Destroys: 

Description: 


Makes  the  next  record  the  current  record, 
none. 

flleHeader  index  table  checked  to  establish  whether  record  exists. 

X         error  ($00  =  no  error). 

y         if  no  error,  then  a  value  of  $00  here  means  record  is  empty, 
a         new  current  record  number. 

Commodore: 

rl        track/sector  of  first  data  block  in  record. 
Appig; 

rl        block  number  of  record's  index  block. 


curRecord 

nothing. 


new  record  number. 


Example: 
See  also: 


NextRecord  makes  the  current  record  plus  one  the  new  current  record.  A 
subsequent  call  to  ReadRecord  or  WriteRecord  will  operate  with  this  record. 

If  the  record  does  not  exist,  then  NextRecord  returns  an  INV  RECORD 
(invalid  record)  em)r.  " 


PointRecord,  PreviousRecord. 
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NormalizeX  (Ci28) 


graphics! 


Function:       Adjust  an  x-coordinate  to  compensate  for  the  higher-resolution  80-column  nKxie. 

Parameters:    x       GEOSREG  —  zero-page  address  of  word-length  GEOS  register  which 

contains  the  word-length  X-coordinate  to  adjust.. 

Returns:        x  unchanged. 

register  passed  as  GEOSREG  parameter  contains  the  adjusted  x-coordinate. 


Destroys:  a 


Description: 


NormalizeX  is  used  by  nearly  every  GEOS  128  routine  that  writes  to  the 
screen.  It  adjusts  an  x-coordinate  (two's  complement  signed  word)  based  on  the 
graphics  mode  (40-  or  80-column)  and  the  status  of  the  special  bits  in  the 
coordinate.  NormalizeX  allows  an  application  to  run  in  botii  40-  and  80-column 
modes  with  a  minimum  of  programming  effort  If  the  proper  bits  in  a  40-column 
coordinate  is  set,  NormalizeX  will  automatically  double  the  value  when  in  80- 
column  mode. 

Since  GEOS  graphics  operations  automatically  call  NormalizeX  to  adjust  the 
coordinates,  most  applications  will  not  need  to  call  it  direcdy. 

Bit  15  of  the  coordinate  specifies  doubling.  Bit  13  adds  one  to  a  doubled 
coordinate  (allowing  odd-pixel  addressing).  Bit  12  is  a  pseudo-sign  bit.  Use  the 
DOUBLE^W  and  ADD1_W  constants  to  access  tiiese  bits. 

If  die  coordinate  might  be  negative,  the  DOUBLE_W  and  ADDl^W  constants 
should  be  exclusive-or'ed  into  the  x-position  so""that  the  sign  Ts  preserved. 
However,  if  die  coordinate  is  guaranteed  to  be  a  positive  numl^r,  the  constants 
may  simply  be  or'ed  in. 

The  GEOSREG  parameter  is  an  actual  zero-page  address.  Usually  this  will  be  a 
GEOS  register  (r0-rl5)  or  an  application's  register  (a0-al5).  If,  for  example,  an 
application  had  a  value  in  r9  which  it  wanted  normalized,  it  would  first  exclusive- 
or  in  the  special  bits,  then  call  NormalizeX  in  the  following  manner: 


Idx 
jsr 


#r9  ;load  x  with  addr  of  r9 

NormalizeX     /normalize  the  val  in  r9 


The  following  breakdown  of  the  word-length  x-coordinate  illustrates  how  the 
special  bits  affect  the  adjustment  process. 


15      14      13      12  11 


I  bl5  |bl4|bi7T 


10 


x-pixel  coordinate  (b0-bl2) 


] 


b0-bl2  x-coordinate  in  pixels  (two's  comp.  number). 

bl3  add  one  to  doubled  x-coordinatc  (flag). 

bl4  x-coordinate  sign-extension  from  bl2  (pseudo  sign-bit). 

b  15  double  x-coordinate  (flag). 
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If  in  40-column  mode,  then  the  special  bits  arc  ignored  and  the  x-coordinatc  is 
returned  to  its  original  state  (the  state  it  was  in  before  any  special  constants  were 
exclusive-or'ed  in). 

If  in  80-column  mode,  then  the  following  applies: 


bl5 

bl4 

bl3 

Effect 

6 

0 

n 

X  value  unchanged  (nomial  positive). 

1 

1 

n 

X  value  unchanged  (normal  negative). 

0 

1 

n 

X  =  x*2hi  (doubled  negative). 

1 

0 

n 

X  =  x*2+n  (doubled  positive). 

Note: 
Example: 


For  more  information,  refer  to  "GEOS  128  X-position  and  Bitmap  Doubling"  in 
Chapter  @gr@. 
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NxtBlkAiloc 


NxtB  Ik  Alloc   (Apple,  C64,  C128) 


mid-level  disk 


Function:       Special  version  of  BlkAIIoc  that  begins  allocating  from  a  specific  block  on  the 
disk. 


Parameters:  r2 


Uses: 


Returns: 


Alters: 


BYTES  —  number  of  bytes  to  allocate  space  for  (word).  Commodore 
version  can  allocate  up  to  32,258  bytes  (127  Commodore  blocks); 
Apple  version  can  allocate  up  to  65,536  bytes  (128  ProDOS  blocks). 


Commodore: 

r3L      START^TR  —  start  allocating  from  this  track  (byte). 

r3H      START^SC — start  allocating  from  this  sector  (byte). 

r6        TSTABLE  —  pointer  to  buffer  for  building  out  track  and  sector  table  of 

the  newly  allocated  blocks,  usually  a  position  within  fileTrScTab 

(word). 

Apple; 

r3        START3LK—  start  allocating  from  tiiis  block  (word). 
curDrive 


Commodore: 

curDirHead 

dir2Headt 

dir3Headt 

interleave^ 


Apple; 

curVBlkno^ 

VBMchangedt 

numVBMBlkst 


this  buffer  must  contain  the  current  directory  header. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 

desired  physical  sector  interleave  (usually  8);  used  by 
setNextFree.  Applications  need  not  set  this  explicidy  — 
will  be  set  automatically  by  internal  GEOS  routines. 


used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  explications  generally  don't  use. 
X         error  ($00  =  no  eiror). 

r2        number  of  blocks  allocated  to  hold  BYTES  amount  of  data. 
Commodore: 

r3L      track  of  last  allocated  block. 
r3H      sector  of  last  allocated  block. 


Apple; 
r3 


last  block  allocated 


Commodore: 
curDirHead 
dir2Headt 
dir3Headt 


BAM  updated  to  reflect  newly  allocated  blocks. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 
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curVBIknot         used  by  VBM  cacheing  routines. 

VBMchangedt      set  to  TRUE  by  VBM  cacheing  routines  to  indicate  cached 
VBM  block  has  changed  and  needs  to  be  flushed 

^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 


Destroys:  Commodore: 
a,  y,  r4-r8. 

Apple: 

a,  y,  r4,  r6,  r7,  rSH, 

Description:  NxtBlkAlloc  begins  allocating  blocks  from  a  speciflc  block  on  the  disk, 
allowing  a  chain  of  blocks  to  be  appended  to  a  previous  chain  while  still 
maintaining  the  sector  interleave.  NxtBlkAlloc  is  essentially  a  special  version  of 
BlkAlIoc  that  starts  allocating  blocks  from  an  arbitrary  block  on  the  disk  rather 
than  from  a  fixed  block.  NxtBlkAlloc  is  otherwise  identical  to  BlkAlIoc. 


C64  &  C128:  The  Commodore  version  of  NxtBlkAlloc  for  appending  more  blocks  to  a  list  of 
blocks  just  allocated  with  BlkAlIoc,  thus  circumventing  the  32,258-byte  barrier. 
Point  TSTABLE  at  the  last  entry  in  a  track/sector  table  (the  terminator  bytes  which 
we  can  overwrite),  load  the  BYTES  parameter  with  the  number  of  bytes  left,  and 
call  NxtBlkAlloc.  The  START  TR  and  START^SC  parameters  in  r3L  and 
r3H  will  contain  the  correct  values  on  return  from  BlkAlIoc.  NxtBlkAlloc 
will  allocate  enough  additional  blocks  to  hold  BYTES  amount  of  data,  appending 
them  in  the  track/sector  table  automatically.  This  combined  list  of  track  and 
sectors  can  then  be  passed  directiy  to  WriteFile  to  write  data  to  the  full  chain  of 
blocks. 


NxtBlkAlloc  does  not  automatically  write  out  the  BAM.  See  PutDirHead  for 
more  information  on  writing  out  the  BAM.  Also,  the  START  7R  parameter 
should  not  be  track  number  of  the  directory  track.  Refer  to  GetFreeDirBlk  for 
more  information  on  allocating  blocks  on  the  directory  track. 

Apple:  The  Apple  version  of  NxtBlkAlloc  builds  out  a  list  of  allocated  blocks  in  the 

internal  indexBIock  buffer  just  as  if  BlkAlIoc  had  been  called:  it  starts  filling 
up  the  table  from  the  beginning,  overwriting  any  block  pointers  that  may  abready 
be  there.  The  only  difference  between  BlkAlIoc  and  NxtBlkAlloc  is  that 
BlkAlIoc  forces  SetNextFree  to  start  searching  for  free  blocks  beginning  at 
the  block  following  the  VBM,  whereas  NxtBlkAlloc  instructs  it  to  stan 
searching  from  the  START JBLK  block.  NxtBlkAlloc  could  be  used  to  append 
blocks  to  an  existing  file  or  record,  but  the  application  would  need  to  manually 
append  the  new  block  pointers  (built-out  in  indexBIock)  to  the  end  of  the 
original  index  block.  For  this  reason,  the  Apple  GEOS  version  of  NxtBlkAlloc 
is  not  especially  useful. 

NxtBlkAlloc  does  not  automatically  flush  the  VBM  cache.  Sec  PutVBM  for 
nx)re  information  on  flushing  the  cache. 

Note:  For  more  information  on  the  scheme  used  to  allocate  successive  blocks,  refer  to 

SetNextFree. 


J  Example: 
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NxtBlkAlloc 

See  also:       BIk Alloc,  SetNextFree,  AIIocateBlock,  FreeBlock. 
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OpenCard 


OpenCard  (Apple) 


card  driver 


Function: 


Open  printer  card  for  access. 


Parameters:  none. 


Returns: 


X 


STATUS  —  card  error  code;  $00  =  no  eiror  (byte) 


Destroys:       assume  a,  y. 

Description:   OpenCard  opens  access  to  the  printer  carcL  The  printer  driver  calls  this  routine 


to  switch  in  the  printer  card's  ROMs.  This  operation  may  be  necessary  before 
each  block  of  data  because  another  card's  ROMs  may  be  enabled  (thQ  disk 
controller  ROMs,  for  example). 

The  printer  driver  sends  blocks  of  data  to  the  printer  between  calls  to  OpenCard 
and  CloseCard. 


Note: 


Do  not  call  OpenCard  without  having  called  InitCard. 


Example: 


See  also: 


InitCard,  CloseCard. 
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OpenDisk 


OpenPisk  (Apple,  C64,  cns) 


high>levcl  disk] 


Function: 

Parameters: 

Uses: 

Returns: 
Alters: 


Open  the  disk  in  the  cunent  drive 


Destroys: 


none 

curDrive 

Commodore: 
driveType 


drive  that  disk  is  in. 


type  of  drive  to  open  (for  shadowing  information). 


X         error  ($00  =  no  error). 

r5        pointer  to  disk  name  buffer  as  returned  from  GetPtrCurDkNm.  This 
is  a  pointer  to  one  of  the  Dr;cCurDkNm  arrays. 


DracCurDkNm 
curDirHead 

Commodore; 
isGEOS 

dir2Headt 
dir3Headt 
driveType 

Apple; 

sysDirBlkno 


curKBlkno 

totNumBIkst 

pathnameBuft 

curVBlknot 

numVBMBIkst 

VBMchangedt 

curDirTabLo 

curDirTabHi 


current  disk  name  array  contains  disk  name, 
current  directory  header. 


set  to  TRUE  if  disk  is  a  GEOS  disk,  otherwise  set  to 
FALSE. 

(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


block  number  of  /SYSTEM  directory.  If  system  directory 
not  found  on  disk,  then  this  number  is  same  as 
curKBlkno. 

block  number  of  root  directory's  key  block, 
total  number  of  blocks  in  volume, 
reset  to  root  directory. 

block  currendy  cached  in  VOLUMEBITMAP 
number  of  VBM  blocks  on  disk, 
set  to  FALSE, 
set  to  root  directory, 
set  to  root  directory. 


Description: 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 

CommQdor;>; 
a,  y»  r0-r4. 

Applg; 

a,  y,  rl,  r4. 

OpenDisk  initiates  access  to  the  disk  in  Ae  current  drive.  OpenDisk  is  meant  to 
be  caUed  after  a  new  disk  has  been  inserted  into  the  disk  drive.  It  prepares  the 
drive  and  disk  variables  for  deaUng  with  a  new  disk.  An  application  will  usually 
call  OpenDisk  immediately  after  calling  SetDevice. 
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OpenDisk 


Note:  Because  GEOS  uses  the  same  allocation  and  file  buffers  for  each  drive,  it  is 

important  to  close  all  files  and  update  the  BAMA^BM  if  necessary  (use 
PutDirHead  or  PutVBM,  respectively)  before  accessing  another  disk. 

C64  &  C128:  OpenDisk  first  calls  NewDisk  to  tell  the  disk  drive  a  new  disk  has  been 
inserted  (if  the  disk  is  shadowed,  the  shadow  memory  is  also  cleared). 
GetDirHead  is  then  called  to  load  the  disk's  header  block  and  BAM  into 
curDirHead.  With  a  valid  header  block  in  memory,  ChkDkGEOS  is  called  to 
check  for  the  GEOS  I.D.  string  and  set  the  isGEOS  flag  to  TRUE  if  the  disk  is 
a  GEOS  disk.  Finally,  OpenDisk  copies  the  disk  name  string  from 
curDirHead  to  the  disk  name  buffer  returned  by  GetPtrCurDkNm. 

Apple:  Apple  GEOS  OpenDisk  resets  the  path  to  the  root  directory,  then  reads  the  disk 

header  into  the  curDirHead  array.  The  volume  disk  name  is  copied  from  this 
buffer  into  the  disk  name  buffer  returned  by  GetPtrCurDkNm.  This  disk  name 
is  also  used  to  build  out  the  initial  pathname  in  pathnames uf  (the  inital 
pathname  is  a  slash  7"  character  followed  by  Ae  null-terminated  disk  name.). 
OpenDisk  also  initializes  the  VBM  cache  and  its  associated  variables,  computing 
the  total  number  of  VBM  blocks  and  reading  the  first  block  into  the  cache.  The 
flag  VBMchanged  is  set  to  FALSE  to  indicate  tiiat  the  cached  VBM  block  in 
memory  matches  its  copy  on  the  disk.  When  all  this  is  done,  OpenDisk  searches 
the  root  directory  for  the  /SYSTEM  directory  (using  FndFillnDir)  and  stores 
the  resulting  block  number  into  sysDirBlkno. 

Example: 

See  also:       ReOpenDisk,  SetDevice,  NewDisk. 
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OpenRecordFile  (Apple,  C64,  cns) 


VLIR  disk 


Function: 

Parameters: 

Uses: 


Returns: 


Alters: 


Destroys: 
Description: 


Open  an  existing  VUR  file  for  access. 

rO  FILENAME — pointer  to  null-terminated  name  of  file  (word). 
curDrive 


CpmrncKlQi?; 
curType 

Apple: 

curKBlkno 


GEOS  64  vL3  and  later  for  detecting  REU  shadowing. 


current  directory. 

^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
X  error  ($00  =  no  error). 

rl        block  number  (Commodore  track/sector)  of  directory  block  containing 
entry. 

rS        pointer  into  diskBlkBuf  to  start  of  directory  entry. 


fileHeader 
usedRecords 
cur  Record 

fileWrittent 
fileSize 

dirEntryBuf 

Apple; 
fileBytes 


buffer  contains  VLIR  index  table. 

number  of  records  in  file  that  are  currendy  in  use. 

current  record  set  to  1  by  default  or  -1  ($ff)  if  there  are  no 

records  in  the  file. 

set  to  FALSE  to  indicate  VLIR  file  has  not  been  written  to. 
total  number  of  disk  blocks  used  in  file  (includes  index 
block,  GEOS  file  header,  and  all  records), 
directory  entry  of  VLIR  file. 


total  number  of  bytes  in  file  (as  picked  up  from  last  from 
bytes  254, 255, 511,  and  512  of  the  master  index  block. 


^used  internally  by  GEOS  disk  routines:  applications  generally  don't  use. 
a,  y,  rl,  r4-r6. 

Before  accessing  the  data  in  a  VLIR  file,  an  application  must  call 
OpenRecordFile.  OpenRecordFile  searches  the  current  directory  for 
FILENAME  and,  if  it  finds  it,  loads  the  index  table  into  fileHeader. 
OpenRecordFile  initalizcs  the  GEOS  VLIR  variables  (both  local  and  global)  to 
allow  other  VLIR  routines  such  as  WriteRecord  and  ReadRecord  to  access 
the  file.  Only  one  VLIR  file  may  be  open  at  a  time.  A  previously  opened  VLIR 
file  should  be  closed  before  opening  another. 

If  an  application  passes  a  FILENAME  of  a  non-VLIR  file,  OpenRecordFile 
will  renim  a  STRUCT^MISMATCH  error. 


Note: 


An  application  can  create  an  empty  VLIR  file  with  SaveFile. 
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C64  &  C128:  Since  Commcxiorc  GEOS  does  not  support  a  Mcrarchical  fUe  system,  the  "cu^ 
directory"  is  actually  the  entire  disk. 

Apple:  Once  a  VLIR  file  is  opened,  the  current  directory  may  be  changed  without 

affecting  access  to  the  file  because  the  index  information  is  kept  in  fileHeader. 

Example: 

See  also:       CIoseRecordFile,  UpdateRecordFile. 
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OutputByte 


OutputByte  (Apple) 


card  driver  I 


Function: 

Parameters: 

Returns: 

Destroys: 

Description: 

Note: 


Example: 
See  also: 


Put  a  byte  of  output  data  to  the  interface  canL 

y         DATA  —  single  ouput  byte  to  send  to  card  (byte) 

X  STATUS  —  card  error  code;  $00  =  no  error  (byte) 

a,  y. 

OutputByte  sends  a  byte  of  data  to  the  card.  The  ready-for-output  flag  may  be 
checked  with  StatusCard  prior  to  calling  OutputByte. 

OutputByte  must  be  called  after  an  OpenCard  and  before  a  CloseCard. 

Most  card  drivers  always  return  NO_ERROR  from  from  OutputByte  due  to  a 
lack  of  memory  to  properly  handle  complex  error  checking. 


InputByte,  StatusCard. 
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Panic  (Apple,  C64,  C128) 


internal  I 


Function: 
Parameters: 


Display  "system  error"  dialog  box. 
Apple  &C»f; 

top  word  on  stack  is  the  system  error  address+2. 

top  eight  bytes  on  stack  are  unused,  next  word  on  stack  is  the  system  error 
address+2 


Returns: 
Description: 


Example: 


Never  returns. 

Panic  puts  up  a  system  error  dialog  box.  It  is  usually  not  called  directly  by  an 
application.  Usually  the  global  GEOS  variable  BRKVector  will  contain  the 
address  of  this  routine  When  GEOS  encounters  a  brk  (opcode:  $00)  instruction 
in  memory,  it  jumps  indirecdy  through  BRKVector  with  system-specific  status 
values  on  die  stack.  This  usually  results  in  a  system  error  dialog  box.  The  hex 
address  in  the  dialog  box  is  the  address  of  the  offending  brk  instruction. 

An  application  that  patches  into  BRKVector  processes  brk  instructions  on  its 
own  may  need  to  simulate  the  normal  GEOS  course  of  events  by  performing  a 
jmp  Panic. 

Although  this  is  not  a  typical  use,  an  application  can  use  Panic  as  a  means  of 
communicating  fatal  error  messages.  This  may  be  useful  in  a  beta-test  version  of  a 
software  product,  for  example. 


FatalError : 

use  Panic  to  send  a  fatal  error  message  to  the  user 


Pass: 


rO 


Error  number 


See  also: 


FatalError: 
IncW 
IncW 


rO 
rO 


.if     (C64  I  I  APPLE) 
PushW  rO 

.else; (C128) 


Idx  #5-1 

10$: 

PushW  rO 
dex 

bne  10$ 
.endif 

jmp  Panic 

DoDlgBox. 


;add  2  to  error  number 
;to  compensate  for  Panic 

; apple  &  c64  only  expect  an  address 
;push  error  number  onto  stack 

;128,  however,  expects  all  kinds  of  internal 
; machine-state  information  (10  bytes  total)  on  the 
; stack.  It  ignores  all  but  the  bottomost  word. 
;place  5  words  (10  bytes)  total  onto  stack 

;push  error  number  onto  stack 

; (use  error  number  repeatedly  as  dummy  value) 

;loop  until  all  done. 


•go  put  up  the  panic  dialog  box 


CONnBEhO'lAL 
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1  <J 


PointRecord  (Apple,  C64,  ci28) 


VLIR  disk 


Function: 
Parameters: 
Uses: 
Returns: 


Alters: 

Destroys: 

Description: 


Make  a  particular  recoijd  the  current  record 
a  RECORD  — ^  record  number  to  make  current  (byte). 

fileHeader  index  table  checked  to  establish  whether  record  exists. 

X         error  ($00  =  no  error). 

y  if  no  error,  then  a  value  of  $00  here  means  record  is  allocated  but  not  in 

use  (has  no  data  blocks), 
a         new  current  record  number. 


Commodore: 
rl  $0000 
$ff00 

other 

Applg; 

rl  $0000 
$ffff 

other 


curRecord 


record  is  not  allocated 

record  is  allocated  but  not  in  use  (has  no  data  blocks);  this 
information  is  already  flaged  in  y. 
track/sector  of  first  data  block  in  record 

record  is  not  allocated 

record  is  allocated  but  not  in  use  (has  no  data  blocks);  this 
information  is  already  flaged  in  y. 

block  number  of  the  index  block  that  corresponds  to  the 
record  (Apple). 

new  record  number. 


nothing. 


PointRecord  makes  RECORD  the  current  record  so  that  a  subsequent  call  to 
ReadRecord  or  WriteRecord  will  operate  with  RECORD.  VLIR  records  are 
numberd  zero  tiirough  MAX_VLIR_RECS-1. 

If  the  record  does  not  exist  (you  pass  a  record  number  that  is  larger  tiian  the 
number  of  currently  used  records),  then  PointRecord  returns  an 
INV  RECORD  (invalid  record)  error. 


Example: 


See  also:     NextRecord,  PreviousRecord. 


PosSprite 


PosSprite  (Apple,  C64,  C128) 


spritej 


Function: 
Parameters: 

Returns: 
Alters: 


Destroys: 
Description: 


C64: 


C128: 


Apple: 

Example: 
See  also: 


Positions  a  sprite  at  a  new  GEOS  (x,y)  coordinate. 

r3L    SPRITE  —  sprite  number  (byte). 
r4      XPOS  —  x-position  of  sprite  (word). 
rSL    YPOS  —  y-position  of  sprite  (byte). 


nothing. 

mobNxpos 
msbNxpos 
reqXposN 
mobnypos 


(64  and  128  only)  sprite  x-position  (lower  8-bits) 
(64  and  128  only)  sprite  x-position  (bit  9). 
(Apple  only)  sprite  x-position. 
(all  versions) 


where  N  is  the  number  of  the  sprite  being  positioned. 
a,  X,  y,  r6 

PosSprite  positions  a  sprite  using  GEOS  coordinates  (not  C64  hardware  sprite 
coordinates).  PosSprite  does  not  affect  the  enabled/disabled  status  of  a  sprite,  it 
only  changes  the  cuirent  position. 

Although  there  are  eight  sprites  available,  an  application  should  only  directiy 
position  sprites  #2  through  #7  with  PosSprite.  Sprite  #0  (the  mouse  pointer) 
should  not  be  repositioned  (except,  maybe  through  mouseXPos  and 
mouse YPos),  and  sprite  #1  (the  text  cursor)  should  only  be  repositioned  witii 
stringX  and  stringY. 

The  positions  are  translated  to  C64  hardware  coordinates  and  then  stuffed  into  the 
VIC  chip's  sprite  positioning  registers.  The  C64  hardware  immediately  redraws 
the  sprite  at  die  new  position. 

The  positions  are  translated  to  C64  hardware  coordinates  and  then  stuffed  into  the 
VIC  chip's  sprite  positioning  registers.  This  data  is  used  by  the  VIC  chip  in  40- 
column  mode  and  by  the  soft-sprite  handler  in  80-column  mode.  In  80-column 
mode,  the  sprite  is  not  visually  updated  until  the  next  time  the  soft-sprite  handler 
gets  control. 

The  y-position  is  stuffed,  unaltered,  into  mobnypos  (simulated  hardware 
register),  and  the  x-position  is  stuffed,  unaltered,  into  reqXposn.  The  sprite  is 
not  visually  updated  until  the  next  time  the  soft-sprite  handler  gets  control. 


DrawSprite,  GetSpriteData,  EnablSprite,  DisablSprite,  InitSprite. 
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PreviousRecord 


PreviousRecord  (Apple,  C64,  cm) 


VLIR  disk 


Function: 
Parameters: 
Uses: 
Returns: 


Alters: 

Destroys: 

Description: 


Makes  the  previous  record  the  current  record, 
none* 

fileHeader  index  table  checked  to  establish  whether  record  exists. 
X         error  ($00  =  no  error). 

y         if  no  error,  then  a  value  of  $00  here  means  record  is  empty, 
a         new  current  record  number. 

CpmrnQ^ore; 

r  1        track/sector  of  first  data  block  in  record 
Apple; 

rl        block  number  of  record's  index  block. 


curRecord 

nothing. 


new  record  number. 


Example: 
See  also: 


PreviousRecord  makes  die  current  record  minus  one  the  new  current  record.  A 
subsequent  call  to  ReadRecord  or  WriteRecord  will  operate  with  this  record. 

If  the  record  does  not  exist,  then  PreviousRecord  returns  an  INV  RECORD 
(invalid  record)  error. 


PointRecord,  NextRecord. 
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PrintASCIi 


Print  ASCII  (Apple,  C64,  C128) 


printer  driver  | 


Function: 
Parameters: 


Uses: 


Send  ASCn  string  to  the  printer. 

rO        PRINTDATA  —  pointer  to  null-terminated  ASCII  string  (word). 

rl  WORKBUF  —  pointer  to  a  640-byte  work  buffer  for  use  by  the  printer 
driver  (word).  This  is  the  same  buffer  that  was  established  in 
StartASCn  and  must  stay  intact  throughout  the  entire  page. 


Apple 
rO 


PRINTDATA  —  pointer  to  null-terminated  ASCII  string  (word). 


Apple 
RWbank 


the  memory  bank  that  the  PRINTDATA  buffer  is  in.  Valid 
settings  aie  MAIN  and  AUX. 


Cpmm«I(?rp 
nothing. 

Apple 

X  STATUS  —  printer  error  code;  $00  =  no  error. 

Commodore 

assume  a,  x,  y,  r0-rl5. 
Apple 

assume  a,  y,  rl-r4. 

« 

Description:  PrintASCIi  sends  a  null-terminated  ASCII  string  to  the  prinier.  The  application 
must  call  StartASCII  before  sending  ASCII  data  to  the  printer  with 
PrintASCIi.  It  is  the  job  of  the  application  to  keep  track  of  the  number  of 
possible  lines  per  page  and  call  StopPrint  to  formfeed  when  necessary  (or 
desired). 

In  order  to  begin  printing  on  the  next  line,  the  string  must  contain  a  CR  character 
to  signify  a  carriage  return.  A  NULL  character  marks  the  end  of  the  string. 

C64  &  C128:  The  data  passed  in  PRINTDATA  is  in  regular  ASCII  format  (not  Conmiodore 
ASCII),  The  text  is  printed  using  the  printer's  standard  character  set.  Some 
printer  drivers  allow  switching  the  printer  into  high-quality  print  mode  with 
SetNLQ.  Commodore  GEOS  printer  drivers  are  set  to  print  80  characters  per 
line  and  66  lines  per  page. 

The  data  passed  in  PRINTDATA  is  in  regular  ASCII  format.  The  text  is  printed 
using  the  printer's  standard  character  set  unless  some  other  option  has  been 
selected  with  the  SetMode  conmiand.  The  page  width  and  height  can  be 
determined  with  GetMode.  Because  a  new  line  is  not  staned  until  a  CR 
character  is  encountered  an  NULL  can  be  inserted  mid-string.  When 
PrintASCIi  encounters  it  and  returns,  the  application  can  call  SetMode  to 
change  the  modes  mid-line. 


Returns: 


Destroys: 


Apple: 


PrintASCII 


Example: 

See  also:       PrintASCII,  StartPrlnt,  StopPrint,  InitForPrint. 
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PrintBuffer  (Apple,  C64,  cns) 


PrintBuffer 


printer  driver 


Function:       Print  one  cardrow  (eight  lines)  of  graphics  data. 

Parameters:  Commodore 

rO        PRINTDATA  —  pointer  to  640  bytes  of  graphic  data  in  Commodore 
card  format  (8x8  pixel  blocks).  This  is  one  row  of  80  cards,  which 
amounts  to  eight  lines  of  printer  data  (word), 
rl        WORKBUF  —  pointer  to  the  1,920-byte  woric  buffer  established  with 
StartPrint  (word). 

r2  COLRDATA  —  pointer  to  80  bytes  of  Ci)mmodore  card  color  data  (40- 
colunm  screen  format)  for  the  cardrow;  pass  $0000  for  normal  black 
and  white  printing  (word). 

Apple 

rO        PRINTDATA  —  pointer  to  640  bytes  of  graphic  data  in  linear  bitmap 

format  This  is  eight  640-bit  rows  of  printer  data  (word). 
rlL      LF.SUPPRESS  —  set  to  TRUE  to  suppress  automatic  linefeed  after 
printing  buffer  (for  overlayed  printing);  normally  set  to  FALSE. 

Apple 

RWbank  the  memory  bank  that  the  PRINTDATA  buffer  is  in.  Valid 

settings  are  MAIN  and  AUX. 

Commodorg 

nothing. 
Applg 

X         STATUS  —  printer  error  code;  $00  =  no  error. 

assume  a,  x,  y,  r0-rl5. 

Apple 

assume  a,  y,  r0-r4. 

Description:  PrintBuffer  prints  eight  lines  of  graphic  data  on  the  printer.  The  maximum 
width  of  each  line  is  determined  by  the  capabilites  of  the  printer  and  its  driver. 
640  dots  per  line  is  standard,  but  some  printers  and  drivers  handle  less.  The 
application  can  determine  the  capabilities  of  the  printer  with  a  call  to 
GetDimensions  (Commodore)  or  GetMode  (Apple).  If  the  printer  cannot 
handle  the  full  640  dots,  PrintBuffer  will  ignore  any  pixels  at  the  end  of  each 
line. 

The  application  must  call  StartPrint  before  sending  graphic  data  to 
'  PrintBuffer.  It  is  also  the  job  of  the  application  to  keep  track  of  the  number  of 
possible  cardrows  per  page  and  call  StopPrint  to  formfeed  when  necessary. 

C64  &  C128:  The  data  passed  in  PRINTDATA  is  in  Commodore  card  format,  where  data  is 
stacked  into  8x8-pixel  blocks.  Graphic  printer  data  can  be  built-up  direcdy  on  the 
40-column  graphics  screen  using  GEOS  routines  and  sent  direcfly  to  the  printer 
(calcinating  the  address  using  GetScanLine).  Because  one  printer  cardrow  is 


Uses: 
Returns: 

Destroys: 
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PrIntBuffer 


equivalent  to  two  screen  caixirows  the  full  640-dot  printer  cardrow  can  be  created 
using  two  sequential  screen  cardrows.The  sequential  memory  organization  of  the 
40-column  screen  wraps  the  end  of  one  screen  cardrow  around  to  the  beginning 
of  the  next  screen  cardrow.  In  the  80-column  mode  of  GEOS  128,  one  screen  line 
is  equivalent  to  one  printer  line.  However,  the  data  must  first  be  converted  from 
linear  bitmap  format  into  card  format  (a  simple  operation).  Also,  since  the 
foreground  screen  can  only  be  accessed  indirectiy  through  the  VDC  chip,  the 
printer  data  is  usually  built-up  in  the  background  screen  buffer. 

Apple:  The  data  passed  in  PRINTDATA  is  in  linear  bitmap  format,  where  the  first  80 

bytes  represent  the  640  bits  that  are  printed  on  the  first  line,  the  next  80  bytes 
represent  the  640  bits  on  the  next  line,  and  so  on  to  fill  out  eight  lines.  Printer  data 
can  be  created  using  the  GEOS  graphics  routines,  then  converted  from  Apple 
internal  screen  format  to  linear  bitmap  format  using  GetLine  and 
GetBackLine. 

With  the  proper  printer  and  driver,  color  output  can  be  created  by  setting  making 
three  passes  per  line,  each  time  printing  in  a  different  color  (cyan,  yellow, 
magenta).  The  first  color  is  set  with  SetMode  and  PrintBuffer  is  called  witii 
the  LF_SUPPRESS  flag  set  to  TRUE,  which  will  return  the  print  carriage 
without  performing  an  linefeed.  The  next  color  can  then  be  printed  on  top  of  what 
is  already  there.  When  calling  PrintBuffer  for  the  third  time  (the  last  color),  set 
the  LFJUPPRESS  flag  to  FALSE,  which  will  carriage  return  and  linefeed. 

Example: 


See  also:       PrintASCII,  StartPrint,  StopPrint,  InitForPrint. 


PrOmptOff  (Apple,  C64,  C128) 


text/keyboard  I 


Function: 

Parameters: 

Alters: 

Destroys: 
Description: 


Example: 
See  also: 


Turn  off  the  prompt  (remove  the  text  cursor  from  the  screen), 
none. 


alphaFlag 


a,  X,  r3L 


(($cO  &  (alphaFlag  &  $40)  I  PROMPT.DELAY),wA^re 
PROMPT  DELAY  =  60. 


PromptOff  removes  the  text  prompt  from  the  screen.  To  ensure  the  prompt  will 
remain  invisible  until  a  subsequent  call  to  PromptOn,  interrupts  must  be 
disabled  before  calling  PromptOff: 


KillPrompt : 
php 
sei 
jsr 
LoadB 
pip 
rts 


PromptOff 
alphaFlag,  #0 


;save  i  status 
/disable  interrupts 
/prompt  »  off 
/clear  alpha  flag 
/restore  i  status 
/exit 


InitTextPrompt,  PromptOn. 


PromptOff- 


PrOmptOn  (Apple,  C64,  Cmy  ^  text/keyboard 

Function:       Turn  on  the  prompt  (show  the  text  cursor  on  the  screen). 
Parameters:  none. 

Uses :  strlngX  cursor  x-position  (word). 

stringY  cursor  y-position  (byte). 

Alters:  alphaFlag  (($cO  &  (alphaFlag  I  $40)  I  PROMPT_DELAY),w/z^r^ 

PROMPT JfELAY  =  60. 

Destroys:       a,  x,  r3L. 

Description:  PromptOn  makes  the  text  prompt  visible  and  active  at  the  position  specified  by 
stringX  and  stringY.  The  prompt  will  flash  once  every  second 
(PROMPT^DELAY).  If  stringX  or  StringY  are  changed,  the  cursor  will 
repositioned  automatically  the  next  time  the  cursor  flashes.  To  make  the  update 
immediate,  call  PromptOn.  Before  PromptOn  is  called  for  the  first  time, 
InitTextPrompt  should  be  called. 

See  also:        InitTextPrompt,  PromptOff. 


Example: 


PurgeTurbo 


IPurgeTurbo  (C64,  cns) 


very  low«levcl  disk] 


Function:  Completely  deactivate  and  remove  disk  drive  turbo  code  from  current  drive, 
rctuming  to  standard  Commodore  DOS  mode. 

Parameters:  none. 

Uses :  curDrive  currcndy  active  disk  drive. 

Returns:        x         error  ($00  =  no  error). 
Destroys:       a,  y,  r0-r3. 

Description:  PurgeTurbo  deactivates  and  removes  the  turbo  software  from  the  current  drive, 
returning  control  of  the  device  to  the  disk  drive's  internal  ROM  software.  This 
allows  access  to  normal  Commodore  DOS  routines.  An  application  may  want  to 
access  the  Commodore  DOS  to  perform  disk  functions  not  offered  by  the  GEOS 
Kemal  such  as  formatting. 

Apple:  Apple  GEOS  has  no  PurgeTurbo  equivalent 

See  also:       EnterTurbo,  ExitTurbo. 
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PutBlock 


PutBlOCk  (Apple,  C64,  C128) 


low-level  disk] 


Function: 
Parameters: 


Uses: 


Returns: 

Destroys: 
Description: 


General  purpose  routine  to  write  a  block  to  disk  with  verify. 

r4        BUFFER  —  address  of  buffer  to  get  block  from;  must  be  at  least 
BLOCKSIZE  bytes  (word). 

Commodore: 

rlL      TRACK — valid  track  number  (byte), 
r IH      SECTOR — valid  sector  on  track  (byte). 

Applg; 

r  1        BLOCK  —  ProDOS  block  number  (word). 
curDrive  currently  active  disk  drive  to  write  to. 


Commodore: 
curType 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing. 


Applg: 

RWbank  bank  BUFFER  is  in  (MAIN  or  AUX). 

numDiskRetries  number  of  times  to  attempt  rewrite  if  verify  fails.  If  $(X),  no 
verify  will  be  perfomied. 

X  error  ($00  =  no  error), 

rl,  r4  unchanged 

a,  y. 

PutBlock  writes  a  block  from  BUFFER  to  the  disk.  PutBlock  is  useful  for 
implementing  disk  utility  programs  and  new  file  structures. 


C64  &  C128:  PutBlock  is  a  higher-level  version  of  WriteBlock.  It  calls  InitForlO, 
EnterTurbo,  ReadBlock,  and  DoneWithlO.  If  an  application  needs  to  write 
many  blocks  at  once,  WriteBlock  may  offer  a  faster  solution.  If  the  disk  is 
shadowed,  PutBlock  will  also  write  the  data  to  the  shadow  memory. 


Apple: 

Example: 
See  also: 


PutBlock  provides  the  lowest-level  block  access  to  a  ProDOS  compatible 
device.  It  uses  the  ProDOS  device  driver  WRITE  block  command  directly. 
Apple  GEOS,  for  this  reason,  does  not  have  a  WriteBlock  equivalent. 


GetBlock,  WriteBlock,  BIkAlloc. 
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PutChar  (Apple,  C64,  C128) 


text 


Function: 
Parameters: 

Uses: 


Returns: 
Destroys: 


Process  a  single  character  code  (both  escape  codes  and  printable  characters). 

a        CHAR  —  character  code  (byte). 

r  1 1    XPOS  —  x-coordinate  of  left  of  character  (word). 

r  1 H    YPOS  —  y-coordinate  of  character  baseline  (word). 


dispBufferOn 

currentMode 

leftMargin 

rightMargin 

(following  set  by 

curHeight 

baseiineOffset 

cardDataPntr 

curlndexTable 

curSetWidth 


display  buffers  to  direct  output  to. 
character  style. 

left  margin  to  contain  character, 
right  margin  to  contain  characters. 
LoadCharSet  and  LoadAuxSet). 
height  of  current  font. 

number  of  pixels  from  top  of  font  to  baseline, 
pointer  to  current  font  image  data, 
pointer  to  current  font  index  table  data, 
pixel  width  of  font  bitstream  in  bytes. 


r  1 1    x-position  for  next  character. 

rl H    y-position  for  next  character  (usually  unchanged). 

Commodore: 

a,  X,  y,  rlL,  r2-rl0,  rl2,  rl3 


Applg; 

a,  X,  y,  rlL,  r2 


"  Description:  PutChar  is  the  basic  character  handling  routine.  If  the  character  code  is  less  than 
32,  PutChar  will  look-up  a  routine  address  in  an  internal  jump  table  to  process 
the  escape  code.  Only  send  implemented  escaped  codes  to  PutChar. 

If  the  character  code  is  32  or  greater,  PutChar  treats  it  as  a  printable  character. 
First  it  establishes  the  .printed  size  of  the  character  with  any  style  attributes 
(currentMode)  then  checks  the  character  position  against  the  bounds  in 
leftMargin  and  rightMargin.  If  the  left  edge  of  the  character  will  fall  to  the  left 
of  leftMargin,  then  the  width  of  the  character  is  added  to  the  x-position  in  rll 
and  PutChar  vectors  through  StringFaultVec.  If  the  right  edge  of  the  characer 
will  fall  to  the  right  of  rightmargin,  then  PutChar  vectors  through 
StringFaultVec  without  altering  the  x-position.  The  character  is  not  printed  in 
either  case. 

Assuming  no  margin  fault,  PutChar  will  print  the  character  to  the  screen  at  the 
desired  position.  Any  portion  of  the  character  that  lies  above  windowTop  or 
below  windowBottom  will  not  be  drawn. 

PutChar  cannot  be  used  to  directly  process  multi-byte  character  codes  such  as 
GOTOX  or  ESC^GRAPHICS  unless  rO  is  maintained  as  a  string  pointer 
when  PutChar  is  called  (as  it  is  in  PutString).  See  PutString  for  more 
information. 


PutChar 


See  also:       SmallPutChar,  PutString,  PutDecimal. 


i 
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PutDecimal  (Apple,  C64,  ci28) 


text 


Function: 
Parameters: 

Uses: 
Returns: 

Destroys: 


Description: 


Format  and  print  a  16-bit  positive  integer. 

a  FORMAT  —  formatting  codes  (byte)  —  see  below. 

rO  NUM  —  16-bit  integer  to  convert  and  print  (word), 

rl  1  XPOS  —  x-coordinate  of  leftmost  digit  (word), 

r  1 H  YPOS  —  y-coordinate  of  baseline  (word). 

same  as  PutChar. 

r  1 1    x-position  for  next  character. 
rlH  unchanged. 

Commodore: 

a,  X,  y,  rO,  rlL,  r2-rl0,  rl2,  rl3 

Applg; 

a,  X,  y,  rO,  rlL,  r2 

PutDecimal  converts  a  16-bit  positive  binary  integer  to  ASCII  and  sends  the 
result  to  PutChar.  The  number  is  formatted  based  on  the  FORMAT  parameter 
bytes  in  the  a-registers  as  follows: 

FORMAT: 


NOTE: 

Example: 
See  also: 


7       6  5 

I  b7  I  b6  I 


bO-b5 


b7  justification:  1  =  left;  0  =  right. 

b6  leading  zeros:  1  =  suppress;  0  =  print. 

b5-bO      field  width  in  pixels  (only  used  if  right  justifying). 

The  following  constants  may  be  used: 

SET  LEFTJUST 
SET"RIGHTJUST 
SET"SUPPRESS 
SET^NOSUPPRESS 

The  maximum  16-bit  decimal  number  is  65535  ($ffff),  so  the  printed  number  will 
never  exceed  five  characters. 


PutChar. 


PutDirHead 


IPutPirHead  (Apple,  C64,  cns) 


mid-level  disk  I 


Function:  Write  directory  header  to  disk.  Commodore  GEOS  also  writes  out  the  BAM. 
Parameters:  none. 


Uses: 


curDrive 
curDirHead 


current  directory  header. 


Returns: 


Destroys: 


Commodore: 

curType  GEOS  64  vL3  and  later  for  detecting  REU  shadowing. 

dir2Headt  (BAM  for  1571  and  1581  drives  only) 

dIrSHeadt  (BAM  for  1581  drive  only) 

^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 

Apple: 

curKBlkno         current  key  block  to  write  directory  header  to. 

X         error  ($00  =  no  error). 

Commodore: 

r4        pointer  to  curDirHead. 

Commodore: 
a,y,  rl. 

Appig; 

a,  y.  rl,  r4. 


Description: 


PutDirHead  writes  the  directory  header  to  disk  from  the  buffer  at  curDirHead. 
Because  of  differences  in  the  Commodore  and  Apple  file  systems,  this  can  mean 
different  things.  Commodore  GEOS  writes  out  the  full  directory  header  block, 
including  the  BAM  (block  allocation  map).  Apple  GEOS  only  writes  out  the  39- 
byte  ProDOS  directory  header  for  die  cuntnt  directory's  key  block. 

C64  &  C128:  GEOS  disks,  like  the  standard  Commodore  disks  upon  which  they  are  based, 
have  one  directory  header.  The  directory  header  occupies  one  full  block  on  the 
disk.  The  Commodore  directory  header  contains  information  about  the  disk,  such 
as  the  location  of  the  directory  blocks,  the  disk  name,  and  the  GEOS  version 
string  (if  a  GEOS  disk).  The  Commodore  directory  header  also  contains  the  disk 
BAM,  which  flags  particular  sectors  as  used  or  unused 

PutDirHead  calls  PutBlock  to  write  out  the  directory  header. block  from  die 
buffer  at  curDirHead.  The  directory  header  block  contains  the  directory  header 
and  the  disk  BAM  (block  allocation  map).  Applications  that  are  working  with  die 
mid-  and  low-level  GEOS  disk  routines  may  need  to  call  PutDirHead  to  update 
die  BAM  on  die  disk  widi  die  BAM  in  memory.  Many  useful,  mid-level  GEOS 
routies,  such  as  BlkAUoc,  only  update  the  BAM  in  memory  (for  sp^d  and  ease 
of  error  recovery).  When  a  new  fdc  is  written  disk,  GEOS  allocates  die  blocks  in 
the  in-memory  BAM,  writes  the  blocks  out  using  the  track  sector  table,  then,  as 
die  last  operation,  calls  PutDirHead  to  write  die  new  BAM  to  die  disk.  An 
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PutDfrHead 


application  that  uses  the  mid-level  GEOS  routines  to  build  its  own  specialized 
disk  file  functions  will  need  to  keep  track  of  the  status  of  the  BAM  in  memory, 
writing  it  to  disk  as  necessary. 

It  is  important  that  the  BAM  in  menx>ry  not  get  overwritten  by  an  outdated  BAM 
on  the  disk.  Applications  that  manipulate  the  BAM  in  memory  (or  calls  GEOS 
routines  that  do  so),  must  be  careful  to  write  out  the  new  BAM  before  calling  a 
routine  that  might  overwrite  it.  Routines  that  call  GetDirHead  include 
OpenDisk,  SetGEOSDisk,  and  OpenRecordFile. 

GEOS  VLIR  routines  set  the  global  variable  fileWritten  to  TRUE  to  signal  that 
the  VLIR  file  has  been  written  to  and  that  the  BAM  in  menx)ry  is  more  recent  than 
the  BAM  on  the  disk.  CloseRecordFile  checks  this  flag.  If  fileWritten  is 
TRUE,  CloseRecordFile  calls  PutDirHead  to  write  out  the  new  BAM. 

Apple:  Apple  GEOS  disks,  like  the  ProDOS  disks  upon  which  they  are  based,  have  a 

directory  header  for  each  directory.  The  header  for  a  root  directory  is  called  a 
volume  directory  header  and  the  header  for  a  subdirectory  is  called  a  subdirectory  > 
header.  These  directory  headers  are  39-byte  structures  defined  by  ProDOS.  They 
contain  such  information  as  the  directory  (or  volume)  name,  the  date  stamp,  and 
any  read/write  access  flags.  The  directory  header  does  not  contain  the  VBM 
(volumen  bit  map,  the  Apple  equivalent  of  a  BAM). 

PutDirHead  first  reads  in  the  key  block  of  the  current  directory  (pointed  at  by 
curKBIkno)  and  copies  the  39-byte  directory  header  information  from 
curDirHead  to  the  key  block,  then  rewrites  the  key  block  to  disk.  Only  these 
39-bytes  in  the  key  block  are  changed. 

Since  Apple  GEOS  does  not  store  the  allocation  map  (VBM)  in  the  directory 
header  10:e  Commodore  GEOS,  it  not  necessary  to  be  as  careful  about  rereading 
the  directory  header.  PutDirHead  only  needs  to  be  called  when  an  application 
explicidy  wants  to  change  the  directory  header,  which  few  applications  (outside 
of  the  deskTop)  will  ever  do.  For  information  on  writing  the  Apple  VBM,  refer  to 
PutVBM. 

Example: 

See  also:        GetDirHead,  GetVBM,  PutVBM. 


V. 
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PutScreenLine 


PutScreenLine  (Apple) 


graphics! 


Function: 
Parameters: 


Uses: 

Returns: 

Destroys: 

Description: 


Note: 

Example: 
See  also: 


Copies  data  from  the  application's  buffer,  in  internal  format,  to  a  byte-aligned 
horizontal  line  on  the  screen. 

rO      DATA  —  address  of  buffer  to  copy  data  from  (word). 
rlH    XINDX  —  byte  in  line  to  begin  with  (seven-bit  Apple  screen  byte)  (byte). 
r2L    XWIDIH  —  width  in  bytes  of  line  (seven-bit  Apple  screen  bytes)  (byte). 
rlL    Y  —  y-coordinate  of  line  (byte). 

where  (XINDX^J.Y)  and  (XINDX^7+XWIDTH,Y)  define  the  endpoints  of  the 
line. 

dispBufferOn: 

bit  7  —  get  data  from  foreground  screen  if  set 
bit  6  —  get  data  from  background  buffer  if  set 
If  both  bits  are  setjoreground  screen  is  used. 

rO      address  of  byte  following  last  byte  in  the  buffer. 

a,  X,  y,  rO,  rlH,  r2L,  r5-r6 

PutScreenLine  copies  bytes  directly  from  the  specified  buffer  to  the  screen 
memory.  The  screen  is  treated  as  a  contiguous  block  of  bytes  even  though,  in 
actualiQ^,  alternate  bytes  lie  in  different  memory  banks. 

Bytes  are  copied  from  the  buffer  pointed  to  by  rO  and  stored  in  screen  memory 
beginning  at  the  byte-index  into  the  line  stored  in  rlH. 

No  clipping  at  the  screen  edge  is  performed;  the  values  passed  are  rssumed  to  lie 
entirely  on  one  screen  line. 


GetScreenLine. 
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■PulOtiHuiiLiiie 


PutString^  i  PutString  (Apple,  C64,  cns) 


text 


Function: 
Parameters: 


Uses: 
Returns: 

Destroys: 
Calls: 

Description: 


Print  a  string  to  the  screen. 
Normal; 

rO      STRING  —  pointer  to  string  data  (word). 

r  1 1    XPOS  —  x-coordinate  of  left  of  first  character  (word). 

r  1 H    YPOS  —  y-coordinate  for  character  baselines  (word). 

Inline: 

data  appears  immediately  after  the  jsr  i^PutString 

.word  XPOS  x-coordinate. 

.byte   YPOS  y-coordinate. 

.byte   STRINGDATA      null  terminated  string  (no  length  limit) 

same  as  PutChar. 

r  1 1    x-position  for  next  character. 

r  1 H    y-position  for  next  character  (usually  unchanged). 

CQmmQjprp 

a,  X,  y,  rlL,  r2-rl0,  rl2,  rl3 

Apple 

a,  X,  y,  rlL,  r2 
PutChar. 

PutString  passes  a  full  string  of  data  to  PutChar  a  character  at  a  time.  It 
maintains  rO  as  a  running  pointer  into  the  string  and  so  supports  multi-byte 
escape  codes  such  as  GOTOXY. 

If  a  character  exceeds  one  of  the  margins,  PutChar  will  vector  through 
stringFaultVec  as  appropriate.  rO,  rll,  and  rlH  will  all  contain  useful  values 
(current  string  pointer,  x-position,  and  y-position,  respectively).  For  more 
information,  refer  to  "String  Faults  (Left  or  Right  Margin  Exceeded)'*  in  Chapter 
XX. 

Basic  operation  of  PutString: 


PutString: 
5$: 


Idy 

Ida 

beq 

jsr 

IncW 

bra 


#0 

(rO),y 
10$ 

PutChar 


;use  zero  offset 
;get  character 


;exit  if  NULL  terminator 
/otherwise  process  char. 


rO 
5$ 


;move  to  next  byte  in  string 
;and  loop  through  again 


10$: 

rts 


/exit 


C64  &  C128:  Unless  a  special  string  fault  routine  is  placed  in  stringFaultVec  prior  to  calling 
PutString,  a  margin  fault  will  be  ignored  and  PutString  will  attempt  to  print 
the  next  character. 


Pur  SriUMC^ 
PulGereenLIno 


Apple:  If  stringFaultVec  contains  $0000  when  PutString  is  called,  Apple  GEOS 

installs  a  temporary  string  fault  routine  that  fast-forwards  through  the  string  to  the 
null-terminator  whenever  a  fault  is  generated.  stringFaultVec  is  restored  with  a 
$0000  when  PutString  exits. 


Example: 
See  also: 


PutChar,  GraphicsString. 


PutVBM  (Apple) 


P  u  1 Q I  r  i  n  s 


mid-level  disk 


Function:       Flush  the  currently  cached  VBM  block,  writing  it  out  to  disk. 

Parameters:  none. 

Uses:  curDrive 

curVBlkno^         block  to  write  cache  to. 

Returns:        x         error  ($00  =  no  error). 

Alters :  VBM  changed^     set  to  FALSE;  indicates  current  cache  matches  disk. 

^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
Destroys:       a,  y,  rl,  r4. 

Description:    PutVBM  writes  the  currently  cached  VBM  block  to  its  proper  spot  on  the  disk. 

This  cache  is  inaccessible  to  applications  but  is  used  indirecdy  by  routines  such  as 
SetNextFree.  PutVBM  is  called  by  high-level  GEOS  routines  to  automatically 
flush  the  cache,  bringing  the  copy  of  the  VBM  on  the  disk  up-to-date  with  the 
copy  in  memory.  Specialized  applications  that  call  mid-  and  low-level  disk 
routines  may  need  to  flush  the  cache  manually. 

Apple  GEOS  disk  routines  cache  a  single  VBM  block  in  an  internal  memory 
buffer.  This  speeds  up  disk  operations  by  allowing  the  VBM  to  be  accessed 
quickly  during  multiple-sector  disk  operations.  This  parallels  the  way 
Commodore  GEOS  buffers  the  BAM  in  the  directory  header.  In  fact,  wherever  a 
Commodore  GEOS  application  calls  PutDirHe^d  to  update  the  BAM  on  the 
disk,  an  Apple  GEOS  application  can  usually  substitute  a  call  to  PutVBM. 

But  there  are  differences  between  the  Commodore  buffering  and  the  Apple 
buffering.  Because  higher-density  storage  devices  (a  hard  disk,  for  example)  will 
have  more  than  one  VBM  block,  the  entire  VBM  cannot  be  stored  in  memory. 
The  Apple  GEOS  routines  that  manage  the  disk  cache  will  automatically  flush  the 
currentiy  cached  VBM  block  before  loading  in  another.  But  if  another  VBM  block 
is  never  loaded,  the  cache  may  not  necessarily  get  flushed.  For  example,  some 
mid-level  routines,  such  as  BlkAlIoc  and  AllocateBlock,  do  not  explicitly 
flush  the  cache  O'ust  as  their  Commodore  counterparts  do  not  call  PutDirHead), 
which  may  mean  that  the  block  in  the  cache  may  be  more  up-to-date  than  the 
block  on  the  disk.  An  application  that  uses  these  mid-level  routines  should  flush 
the  cache  manually  with  a  calls  to  PutVBM. 

The  less  often  the  cache  is  flushed,  the  faster  a  multiple-sector  disk  operation  will 
run.  GEOS  VLIR  routines,  for  example,  do  not  flush  the  cache  until 
CioseRecord  is  called.  At  the  very  least,  the  application  must  be  careful  to  flush 
the  VBM  cache  before  calling  any  other  routine  that  might  call  Get  VBM  because 
GetVBM  will  overwrite  die  cached  block  before  it  is  used  to  update  the  disk 
copy.  GetVBM  is  called  by  routines  such  as  OpenDisk  and  BlkAlIoc. 


Note: 


PutVBM  will  write  out  the  cached  VBM  block  even  if  VBMchanged  is 
FALSE. 


PutVBM 


Example: 

See  also:       GetVBM,  GetDirHead,  PutDirHead. 
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ReadBackLine 


ReadBackLine  (Apple) 


graphics 


Function: 

Parameters: 

Returns: 

Destroys: 

Description: 

Example: 


Translates  a  screen  line  in  the  background  buffer  from  internal  format  to  linear 
bitmap  format 

rO      DATA  —  address  of  buffer  to  copy  data  to  (word), 
r  IL    Y  —  y-coordinatc  of  line  (byte). 

rO      address  of  byte  following  last  byte  in  the  buffer. 

a,x,  y,  rO 

ReadBackLine  reads  bytes  direcdy  from  the  background  buffer  and  converts 
them  into  linear  bitmap  foraiat  in  the  application's  buffer.  The  buffer  pointed  to 
by  DATA  must  be  at  least  SC  PIX  WIDTH/7  =  80  bytes  long. 
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ReadBlock 


ReadBlock  (C64,  cns) 


very  low«level  disk} 


Function: 
Parameters: 

Uses: 

Returns: 

Destroys: 

Description: 


Apple: 
Example: 


Very  low-level  read  block  from  disk. 

rlL    TRACK  —  valid  track  number  (byte), 
rlH    SECTOR — valid  sector  on  track  (byte). 

r4      BUFFER  —  address  of  buffer  of  BLOCKSIZE  bytes  to  read  block  into 
(word). 


curDrive 
curType 


currently  active  disk  drive. 

GEOS  64  vl.3  and  later,  for  detecting  REU  shadowing. 


error  ($00  =  no  error). 


a,  y. 


ReadBlock  reads  the  block  at  the  specified  TRACK  and  SECTOR  into 
BUFFER.  If  the  disk  is  shadowed,  ReadBlock  will  read  from  the  shadow 
memory.  ReadBlock  is  a  pared  down  version  of  GetBlock.  It  expects  the 
application  to  have  already  called  EnterTurbo  and  InitForlO.  By  removing 
this  overhead  from  GetBlock,  multiple  sector  reads  can  be  accomplished 
without  the  redundant  initialization.  This  is  exacdy  what  happens  in  many  of  the 
higher-level  disk  routines  that  read  multiple  blocks  at  once,  such  as  ReadFile. 

ReadBlock  is  useful  for  multiple-sector  disk  operations  where  speed  is  an  issue 
and  the  standard  GEOS  routines  don't  offer  a  decent  solution.  ReadBlock  can 
function  as  the  foundation  of  specialized,  high-speed  disk  routines. 

Apple  GEOS  has  no  ReadBlock  equivalent  Use  GetBlock  instead. 


Read  sector  from  disk  into  diskBlkBuf . 
very-low  level  disk  primitives. 


Demonstrates  use  of 


Pass: 

track 
sector 

Returns: 

X 

MyGetBlock: 


track  number 
sector  on  track 


error  code 


99$: 


LoadW 

r4,«diskBlkBuf 

MoveB 

rlLrtrack 

MoveB 

rlH, sector 

jsr 

EnterTurbo 

txa 

bne 

99$ 

jsr 

InitForlO 

jsr 

ReadBlock 

jsr 

DoneWithIO 

rts 

; where  to  get  data  from 
; track  number 
; sector  number 
;go  into  turbo  mode 
;set  status  flags 
/branch  if  error  found 
/prepare  for  serial  I/O 
/primitive  read  block 
/restore  after  I/O  done 

/  exit 


See  also:       GetBlock,  WriteBlock,  VerWriteBlock. 
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IReadByte  (Apple,  C64,  cns) 


mid-level  disk 


Function:       Special  version  of  ReadFile  that  allows  reading  a  chained  list  of  blocks  a  byte  at 

a  time- 
Parameters:    on  initial  call  only: 

r4      BLOCKBUF  —  pointer  to  temporary  buffer  of  BLOCKSIZE  bytes  for 
use  by  ReadByte,  usually  a  pointer  to  diskBlkBuf  (Apple  GEOS:  must 
be  in  main  memory)  (woid). 
rS      $0000  (word). 

Commodore: 

r  1      START^TRSC  —  track/sector  of  first  data  block  (word). 
Apple: 

rl      INDXBLKPTR  —  pointer  to  index  buffer  that  contains  index  block  of 
chain  to  read  (must  be  in  main  memory)  (word). 


Uses: 


curDrive 

Commodore: 
curType 

Apple: 
RWbank 


GEOS  64  V  1.3  and  later  for  detecting  REU  shadowing, 
bank  BUFFER  is  in  (MAIN  or  AUX). 


Returns: 


Destroys: 
Description: 


a       byte  returned 

X       error  ($00  =  no  error). 

rl,  r4,  rS    contain  internal  values  that  must  be  preserved  between  calls  to 
ReadByte. 


ReadByte  allows  a  chain  of  blocks  on  the  disk  to  be  read  a  byte  at  a  time.  The 
first  time  ReadByte  is  called,  rl,  r4,  and  r5  must  contain  the  proper 
parameters.  When  ReadByte  returns  without  an  error,  tiic  a  register  will  contain 
a  single  byte  of  data  fix^m  the  chain.  To  read  another  byte,  call  ReadByte  again. 
Between  calls  to  ReadByte,  the  application  must  preserve  rl,  r4,  r5,  and  the 
data  area  pointed  to  by  BLOCKBUF.  Apple  GEOS  applications  must  also 
preserve  the  512-byte  index  block  pointed  to  by  INDXBLKPTR  and  the  status  of 
RWbank. 

ReadByte  loads  a  block  into  BLOCKBUF  and  returns  a  single  byte  from  the 
buffer  at  each  call.  After  returning  die  last  byte  in  the  buffer,  ReadByte  loads  in 
the  next  block  in  the  chain  and  starts  again  from  the  beginning  of  BLOCKBUF. 
This  process  continues  until  there  are  no  more  bytes  in  the  file.  A 
BFR  OVERFLOW  error  is  then  returned. 


ReadByte  is  especially  useful  for  displaying  very  large  bitmaps  with 
BitOtherCIip  and  NewBitOtherCIip. 


ReadBlock 


C64  &  C128:  Reading  a  chain  a  byte  at  a  time  under  Commodore  GEOS  involves  finding  the 
first  data  block  and  passing  its  track/sector  to  ReadFile.  The  tracl^sector  of  the 
first  data  block  in  a  sequential  file  is  returned  in  rl  by  GetFHdrlnfo.  TTie  first 
data  block  of  a  VLIR  record  is  contained  in  the  VLIR^s  index  table. 

Apple:  Because  the  ProDOS  filing  system  is  different  from  the  Commodore  filing 

system,  different  steps  are  involved  in  using  ReadByte.  The  Apple  GEOS 
version  of  GEOS  expects  an  entire  index  block  for  the  chain,  not  merely  an  initial 
track/sector  as  the  Commodore  version  does.  The  index  block  for  a  sequential  file 
is  returned  in  rl  by  GetFHdrlnfo,  but  it  must  be  loaded  into  memory  with 
GetBIock.  The  index  block  for  a  VLIR  record  is  contained  in  the  VLIR's  index 
table. 

Example: 

See  also:      GetFile,  WriteFile,  ReadRecord. 


ReadClock  (Apple) 


clock  driver 


Function:       Causes  the  clock  driver  to  update  the  global  GEOS  clock  variables  with  the 
current  time.  Called  during  MainLoop  Level  by  GEOS. 


Parameters:  none. 

Returns:  nothing. 

Alters:  year 
month 
day 
hour 
minutes 
seconds 
alarmOn 


updated  firom  clock  device 
updated  firom  clock  device 
updated  firom  clock  device 
updated  from  clock  device 
updated  firom  clock  device 
updated  firom  clock  device 

if  bit  7  set  and  time  for  alarm  to  trigger,  then  bit  7  is  cleared 
and  bit  6  is  set  (byte  is  shifted  right  once). 


Destroys:       assume  x,  y,  r0-rl5. 

Description:  GEOS  calls  ReadClock  during  MainLoop  Level.  ReadClock  is  expected  to 
update  the  global  clock  variables  with  the  current  time.  It  also  checks  for  an  alarm 
trigger  and  sets  alarmOn  appropriately.  (Depending  on  the  clock,  an  alarm 
trigger  may  be  flagged  automatically  in  hardware  or  may  have  be  generated  in 
sofD^are  by  comparing  the  current  time  with  an  internal  alarm  time.) 


See  also: 


Clockint,  SetTimeDate,  SetAlarm,  ResetAlarm. 
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neadCloek 


ReadFile  (Apple,  C64,  ci28) 


mid-Ievel  disk 


Function: 
Parameters: 


Uses: 


Read  a  chained  list  of  blocks  into  memory, 

r7      BUFFER — pointer  to  buffer  where  data  will  be  read  into  (word). 

r2  BUFSIZE  —  size  of  buffer  Commodore  version  can  read  up  to  32,258 
bytes  (127  Commodore  blocks);  Apple  version  can  read  up  to  the 
maximum  two-byte  number  that  can  be  passed  in  r2:  65,535  ($ffff)  bytes 
(word). 

CpmmpdQTg; 

rl      START.TRSC—  track/sector  of  first  data  block  (word). 
Apple; 

r  1      INDXBLXDCK  —  block  number  of  index  block  for  chain  (word). 
curDrive 


Cpmrnodore; 
curType 

Apple; 
RWbank 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing, 
bank  BUFFER  is  in  (MAIN  or  AUX). 


Returns:        x       error  ($00  =  no  error). 

r?      pointer  to  last  byte  read  into  BL/FFfi?  plus  one. 

Commodore: 

rl  if  BFR^OVERFLOW  error  returned,  contains  the  track/sector  of  the 
block  that,  had  it  been  copied  from  diskBlkBuf  to  the  application's 
buffer  space,  would  have  exceeded  the  size  of  BUFFER.  The  process  of 
copying  any  extra  data  from  diskBlkBuf  to  the  end  of  BUFFER  is  left 
to  the  application.  The  data  starts  at  diskBlkBuf+2.  If  no  error,  then  rl 
is  destroyed. 

rSL  byte  index  into  fileTrScTab  of  last  entry  (last  entry  =  fileTrScTab 
plus  value  in  rS). 

Apple: 

r  1  if  BFR_OVERFLOW  error  returned,  contains  the  number  of  die  block 
that  would  have  overwritten  the  end  of  BUFFER  had  the  entire  block  been 
read  direcdy  into  memory.  BUFFER  is  filled  with  as  much  data  from  the 
block  as  will  fit.  If  no  error,  then  rl  is  destroyed. 


Alters:  Commodore: 

fileTrScTab  As  the  chain  is  followed,  the  track/sector  pointer  to  each 
block  is  added  to  die  file  track/sector  table.  The  track  and 
sector  of  the  first  data  block  is  added  at  fiIeTrScTab+2  and 
fiIeTrScTab+3,  respectively,  because  die  first  two  bytes 
(fileTrScTab+0  and  fileTrScTab+1)  are  reserved  for  the 
GEOS  file  header  track/sector. 


RedilCluck 


Apple; 

INDEXBLOCKBUF      index  block  for  chain  (in  auxiliary  memory;  see 

below  for  information  on  accessing  this  buffer). 

Destroys:  Apple: 

y,  (rl),  r3-r4  (see  above  for  rl). 

CPTnmpdore; 

y,  (rl),  r2-r4  (see  above  for  rl). 

Description:    ReadFile  reads  a  chain  of  blocks  from  the  disk  into  memory  at  BUFFER. 

Although  the  name  implies  that  it  reads  "files"  into  memory,  it  actually  reads  a 
chain  of  blocks  and  doesn't  care  whether  this  chain  is  a  sequential  file  or  a  VLIR 
record  —  ReadFile  merely  reads  blocks  until  it  encounters  the  end  of  the  chain 
or  overflows  the  memory  buffer. 

ReadFile  can  be  used  to  load  VLIR  records  from  an  unopened  VLIR  file. 
geoWrite,  for  example,  loads  different  fonts  while  another  VLIR  file  is  open  by 
looking  at  all  the  font  file  index  tables  and  remembering  the  index  information  for 
records  that  contain  font  data.  When  a  VLIR  docimient  file  is  open,  geoWrite 
can  load  a  different  font  by  passing  one  of  these  saved  values  in  rl  to  ReadFile. 
ReadFile  will  load  the  font  into  memory  without  disturbing  the  opened  VLIR 
file. 

For  reading  a  file  when  only  the  filename  is  known,  use  the  high-level  GetFile. 

C64  &  C128:  The  Conimodore  filing  system  links  blocks  together  with  track/sector  links:  each 
block  has  a  two-byte  track/sector  forward-pointer  to  the  next  sector  in  the  chain 
(or  $00/$ff  to  signal  the  end).  Reading  a  chain  involves  passing  the  first 
track/sector  to  ReadFile.  The  first  block  contains  a  pointer  to  the  next  block,  and 
so  on.  The  whole  chain  can  be  followed  by  reading  successive  blocks. 

ReadFile  reads  each  256-byte  block  into  diskBlkBuf  and  copies  the  254  data 
bytes  (possibly  less  in  the  last  block  of  the  chain)  to  the  BUFFER  area  and  copies 
the  two-byte  track/sector  pointer  to  flleTrScTab.  This  process  is  repeated  until 
the  last  block  is  copied  into  the  buffer  or  when  there  is  more  data  in  diskBlkBuf 
than  there  is  room  left  in  BUFFER. 

when  there  is  more  data  in  diskBlkBuf  than  there  is  room  left  in  BUFFER, 
ReadFile  returns  with  a  BFR_OVERFLOW  error  without  copying  any  data 
into  BUFFER.  The  applicatioiTcan  copy  data,  starting  at  diskBlkBuf+2,  to  fill 
the  remainder  of  BUFFER  manually. 

Because  of  the  limited  size  of  fileTrScTab  (256  bytes),  ReadFile  cannot  load 
more  than  127  blocks  of  data.  (256  total  bytes  divided  by  two  bytes  per 
track/sector  minus  two  bytes  for  the  GEOS  file  header  equals  127.)  127  blocks 
can  hold  127  *  254  =  32,258  bytes  of  data. 

Apple:  Unlike  die  Commodore  filing  system,  die  ProDOS  filing  system  links  blocks 

together  with  entries  in  an  index  block:  each  entry  in  the  index  block  holds  a  two- 
byte  block  number.  Going  through  each  entry  constitutes  walking  die  chain.  For 


floadClook 


this  reason,  reading  a  chain  involves  passing,  not  the  first  data  block,  but  the 
block  number  of  the  index  block. 

Apple  GEOS  first  reads  the  index  block  into  the  internal  buffer 
INDEXBLOCKBUF  (in  auxiliary  memory),  then  reads  in  the  blocks  specified 
in  the  index. 

Applications  cannot  direcdy  access  the  auxiliary  buffer  INDEXBLOCKBUF. 
However,  MoveAuxData  can  be  used  to  copy  the  block  into  the  appliciation's 
memory  space  if  access  to  it  is  necessary: 


AUXtoMAIN 
MAINtoAUX 


%10000000 
%01000000 


LoadW  rO,   # INDEXBLOCKBUF 

LoadW  rl,  #diskBlkBuf 

LoadW  r2,  #BLOCKSIZE 

Ida  #AUXtoMAIN 

jsr  MoveAuxData 


;copy  from  index  blk 
;to  temp  buffer 
;move  a  full  block 
;copy  aux  to  main 


Apple  GEOS  ReadFile  could  conceivably  load  up  to  65,536  bytes  of  data  into 
memory.  This  is  of  litde  use,  however,  because  the  absence  of  large,  usable 
memory  blocks  functionally  limits  reads  to  32K  or  64  blocks. 


Example: 
See  also: 


GetFile,  WriteFile,  ReadRecord. 
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ReadLink  (C64,  ci28) 


very  low-level  disk 


isk] 


Function: 
Parameters: 

Uses: 

Returns: 

Alters: 

Destroys: 

Description: 


Apple: 

Example: 
See  also: 


Read  link  (first  two  bytes)  from  a  Commodore  disk  block 

rlL    TRACK  —  valid  track  number  (byte), 
r  1 H    SECTOR  —  valid  sector  on  track  (byte). 

r4      BUFFER  —  address  of  buffer  of  at  least  BLOCKSIZE  bytes,  usually 
points  to  diskBIkBuf  (word). 

curDrive  currently  active  disk  drive. 

X       error  ($00  =  no  error). 

diskBIkBuf 

a,  y. 

ReadLink  returns  the  track/sector  link  from  a  disk  block  as  the  first  two  bytes  in 
BUFFER.  The  remainder  of  BUFFER  (BLOCKSIZE-2  bytes)  may  or  may  not 
be  altered, 

ReadLink  is  useful  for  following  a  multiple-sector  chain  in  order  to  build  a 
track/sector  table.  It  mainly  of  use  on  1581  disk  drives,  which  walk  through  a 
chain  significantly  faster  when  only  the  links  are  read.  Routines  such  as 
DeleteFile  and  FollowChain  will  automatically  take  advantage  of  this 
capability  of  1581  drives. 

Disk  drives  that  do  not  offer  any  speed  increase  through  ReadLink  will  simply 
perform  a  ReadBIock. 

Apple  GEOS  has  no  ReadLink  equivalent;  ProDOS  blocks  are  linked  by  the 
index  block. 


ReadBIock,  FollowChain. 


Wore;     Does       *vo«a:       isHI  Oltr\jsnij  (/S€  tt^/umiac^ 


ReadRecord 


ReadRecord  (Apple,  C64,  ci28) 


VLIR  disk 


Function: 
Parameters: 


Uses: 


Read  in  the  current  VLIR  record. 

r7      BUFFER  —  pointer  to  start  buffer  where  data  will  be  read  into  (word), 
r2      BUFSIZE  —  size  of  buffer:  Commodore  version  can  read  up  to  32,258 
bytes  (127  Commodore  blocks);  Apple  version  can  read  up  to  the 
maximum  two-byte  number  that  can  be  passed  in  r2:  65,535  ($ffff)  bytes 
(word). 


curDrive 

curRecord 

fileHeader 

Commodorp; 
curType 

Apple; 
RWbank 


current  record  pointer 

index  table  holds  first  block  of  record 


GEOS  64  vl.3  and  later,  for  detecting  REU  shadowing, 
bank  RECDATA  is  read  into  (MAIN  or  AUX). 


Returns: 


Alters: 


X       error  ($(X)  =  no  error). 

a       $00  empty  record,  no  data  read. 

$ff  =  record  contained  data. 
r7      pointer  to  last  byte  read  into  BUFFER  plus  one  if  not  an  empty  record, 

otherwise  unchanged. 

ComPOdprp; 

rl  if  BFR  OVERFLOW  error  returned,  contains  the  track/sector  of  the 
block  tfiat,  had  it  been  copied  from  diskBlkBuf  to  the  application's 
buffer  space,  would  have  exceeded  the  size  of  BUFFER.  The  process  of 
copying  any  extra  data  from  diskBlkBuf  to  the  end  of  BUFFER  is  left 
to  the  application.  The  data  starts  at  diskBlkBuf+2.  If  no  error,  then  rl 
is  destroyed 


Apple; 
rl 


if  BFR_0 VERFLOW  error  returned,  contains  the  number  of  the  block 
that  would  have  overwritten  the  end  of  BUFFER  had  the  entire  block  been 
read  directly  into  memory.  BUFFER  is  filled  with  as  much  data  fix)m  the 
block  as  will  fit.  If  no  error,  then  rl  is  destroyed. 


CpmmcKlorg; 
fileXrScTab 


As  the  chain  blocks  in  the  record  is  followed,  the  track/sector 
pointer  of  each  block  is  added  to  the  file  track/sector  table. 
The  track  and  sector  of  the  first  block  in  the  record  is  added 
at  fiIeTrScTab+2  and  fiIeTrScTab+3.  Refer  to 
ReadFile  for  more  infOTmatibn. 


Destroys:  Apple: 

y,  (rl),r3-r4  (see  above  for  rl). 


Commodore: 
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ReadRecord 


y,  (rl),  r2-r4  (sec  above  for  rl). 

Description:  ReadRecord  reads  the  current  record  into  memory  at  BUFFER.  If  the  record 
contains  more  than  BUFSIZE  bytes  of  data,  then  a  BFR_OVERFLOW  error  is 
returned. 

ReadRecord  calls  ReadFile  to  load  the  chain  of  blocks  into  memory. 

Example: 

See  also:     WriteRecord,  ReadFile. 


229 


ReadScanLine 


ReadScanLine  (Apple) 


graphics! 


Function: 

Parameters: 

Returns: 

Destroys: 

Description: 

Example: 


Translates  a  screen  line  on  the  foregorund  screen  from  internal  format  to  linear 
bitmap  format 

rO      DATA  —  address  of  buffer  to  copy  data  to  (word), 
r  IL    Y  —  y-coordinatc  of  line  (byte). 

rO      address  of  byte  following  last  byte  in  the  buffer, 

a,x,y,  rO 

ReadScanLine  reads  bytes  direcdy  from  the  foreground  screen  and  converts 
them  into  linear  bitmap  format  in  the  application's  buffer.  The  buffer  pointed  to 
by  DATA  must  be  at  least  SC  PIX  WIDTH/7  =  80  bytes  long. 
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RecoverAIIMe 


RecoverAllMenus  (Apple,  C64,  cns) 


icon/menu 


Function: 

Parameters: 

Destroys: 

Description: 


Example: 
See  Also: 


Removes  all  menus  (including  the  main  menu)  from  the  foreground  screen  by 
recovering  from  the  background  buffer. 

none. 

assume  r0-rl5,  a,  x,  y 

RecoverAllMenus  is  a  very  low-level  menu  routine  which  recovers  the  area 
obscured  by  the  opened  menus  from  the  background  buffer.  Usually  this  routine 
is  only  called  internally  by  the  higher-level  menu  routines.  It  is  of  little  use  in 
most  applications  and  is  included  in  the  jump  table  mainly  for  historical  reasons. 

RecoverAllMenus  operates  by  loading  the  proper  GEOS  registers  with  the 
coordinates  of  the  menu  rectangles  and  calling  the  routine  whose  address  is  in 
recoverVector  (normally  RecoverRectangle)  repeatedly. 


DoPreviousMenu,  ReDoMenu,  GotoFirstMenu,  RecoverMenu. 


233 


RecoverFG 


ReCOVerFG  (Apple)  graphics/utiUty 


Function:       Restores  a  portion  of  the  foreground  screen  from  data  saved  with  SaveFG. 

Parameters:    rO      FGSTRUCT  —  pointer  to  an  FG  data  structure  (word). 

rl      FGDATA  —  pointer  to  SaveFG  data  to  restore  (word). 

Returns:        Foreground  screen  restored. 

Destroys:       a,  x,  y,  rl-r6. 

Description:   RecoverFG  restores  a  rectangular  area  of  the  foreground  screen  saved  with 
SaveFG. 

FGSTRUCT  points  to  an  FG  data  structure,  which  is  in  the  following  format: 

FGSTROCTl : 

•  word  XI  ; pixel  x-position  of  left  edge 

•  byte  Yl  ; pixel  y-position  of  top  edge 

.word  X2  ;pixel  x-position  of  right  edge  (XI  +  WIDTH) 

.byte  HEIGHT  ;pixel  height  (Y2  -  Yl) 

The  FG  data  structure  used  to  restore  an  area  should  be  the  same  as  the  one  used 
to  save  the  area. 

Example: 

See  also:  SaveFG. 
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RecoverLine  (Apple,  C64,  cns) 


graphics 


Function: 
Parameters: 

Returns: 
Destroys: 

Description: 

Note: 
128: 

Example: 
See  also: 


Recovers  a  horizontal  line  from  the  background  buffer  to  the  foreground  screen. 

r3      XI  —  x-coordinate  of  leftmost  cndpoint  (word). 
r4      X2  —  x-coordinate  of  rightmost  endpoint  (word). 
rllL  Yl  —  y-coordinate  of  line  (byte). 

where  (X1,Y1)  and  (X2,Y1)  define  the  endpoints  of  the  line  to  recover. 

nothing 

Commodore 
a,  x,  y,  r5-r8 

Applg 
a,  X,  y 

RecoverLine  recovers  the  pixels  which  fall  on  the  horizontal  line  whose 
coordinates  are  passed  in  the  GEOS  registers.  The  pixel  values  are  copied  from 
the  background  buffer  to  the  foreground  screen. 

The  flags  in  dispBufferOn  are  ignored;  the  pixels  are  always  copied  to  the 
foreground  screen  regardless  of  the  value  in  this  variable. 

Under  GEOS  128,  oring  DOUBLE  W  into  theXi  andX2  parameters  will 
automatically  double  the  x-position  in  SD-column  mode.  Or*ing  in  ADDl  W  will 
automatically  add  1  to  a  doubled  x-position.  (Refer  to  "GEOS  128  X-posiuon  and 
Bitmap  Doubling"  in  Chapter.®  gr@  for  more  information.) 


ImprintLine,  HorizontalLine,  InvertLine^VerticalLine  ,  DrawLine. 


RecoverMenu 


RecoverMenu  (Apple,  C64,  cns) 


icon/menu 


Function:       Removes  the  current  menu  from  the  foreground  screen  by  recovering  from  the 
background  buffer. 

Parameters:  none. 

Destroys:       assume  r0-rl5,  a,  x,  y 


Description: 


RecoverMenu  is  a  very  low-level  menu  routine  which  recovers  the  rectangular 
area  obscured  by  the  current  menu.  Usually  this  routine  is  only  called  internally 
by  the  higher-level  menu  routines  such  as  DoPreviousMenu.  It  is  of  little  use 
in  most  applications  and  is  included  in  the  jump  table  mainly  for  historical 
reasons. 


RecoverMenu  operates  by  loading  the  proper  GEOS  registers  with  the 
coordinates  of  the  current  menu's  rectangle  and  calling  the  routine  pointed  to  by 
recoverVector  (normally  RecoverRectangle). 

Example: 

See  Also:       DoPreviousMenu,  ReDoMenu,  GotoFirstMenu,  RecoverAllMenus. 


Recover  Rectan^e 


RecoveriRectangle^  i  Recoveif^ectangle  (Apple,  C64,  ci28)  graphkTI 

Function:       Recovers  the  pixels  within  a  rectangular  region  fSrom  the  background  buffer  to  the 
foreground  screen. 

Parameters:  Normal: 

r3      XI  —  x-coordinate  of  upper-left  (word). 
r2L    Y 1  —  y-coordinate  of  upper-left  (byte). 
r4      X2  —  x-coordinate  of  lower-right  (word). 
r2H    Y2  —  y-coordinateof  lower-right  (byte). 

Inline: 

data  appears  immediately  after  the  jsr  i_RecoverRectangIe 
.byte   Yl    y-coordinate  of  upper-left.  " 
.byte   Y2   y-coordinate  of  lower-right 
.word  XI   x-coordinate  of  upper-left 
.word  X2   x-coordinate  of  lower-right 

where  (XI, Yl )  is  the  upper-left  corner  of  the  rectangular  area  and  (X2,Y2)  is  the 
lower-right  corner. 

Returns:        r2,  r3,  and  r4  unchanged. 

Destroys:  Commodore: 

a,  X,  y,  r5-r8,  rllL 

Appig; 

a,  X,  y,  rllL 

« 

Description:   RecoverRectangle  copies  the  pixels  within  a  rectangular  region  from  the 
background  buffer  to  the  foreground  screen  by  calling  RecoverLine  in  a  loop. 

Note:  The  flags  in  dispBufferOn  are  ignored;  the  pixels  are  always  copied  to  the 

foreground  screen  regardless  of  the  value  in  this  variable. 

128:  Under  GEOS  128,  orlng  DOUBLE  W  into  theX7  andX2  parameters  will 

automatically  double  the  x-position  in  SD-column  nxxie.  (Dr'ing  in  ADDl  W  will 
automatically  add  1  to  a  doubled  x-position.  (Refer  to  "GEOS  128  X-posi'Hon  and 
Bitmap  Doubling"  in  Chapter.®  gr@  for  more  information.) 

Example: 


See  also: 


ImprintRectangle,  Rectangle,  InvertRectangle. 


RecoverSysRam 


RecoverSysRam  (Apple)  int^^ 

Function:       Restores  the  system  state  after  a  call  to  InitForDialog. 
Parameters:  none. 

Returns:        system  restored  to  its  prior  state. 
Destroys:       a,x,  y,  rl,  r2,  r3Ly  r4. 

Description:   RecoverSysRam  restores  the  state  of  GEOS  that  was  saved  with 
InitForDialog. 

See  also:  InitForDialog. 
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[Rectangle,  i  Rectangle  (Apple,  C64,  cns)  graphics! 


Function: 
Parameters: 


Uses: 


Returns: 
Destroys: 


Description: 


Note: 


Draw  a  rectangle  in  the  current  fill  pattern. 
Normal: 

r3      XI  —  x-coordinate  of  upper-left  (word). 
r2L    Yl  —  y-coordinate  of  upper-left  (byte). 
r4      X2  —  x-coordinate  of  lower-right  (word). 
r2H    Y2  —  y-coordinate  of  lower-right  (byte). 

where  (XI, Yl )  is  the  upper-left  corner  of  the  rectangle  and  (X2,Y2)  is  the  lower- 
right  corner. 

Inline: 

data  appears  immediately  after  the  jsr  i^Rectangle 
.byte   Yl    y-coordinate  of  upper-left 
.byte   Y2    y-coordinate  of  lower-right, 
.word  X 1    x-coordinate  of  upper-left 
.word  X2   x-coordinate  of  lower-right 

dispBufferOn: 

bit  7  —  write  to  foreground  screen  if  set. 
bit  6  —  write  to  background  screen  if  set 

nothing 

Commodore: 
a,  X,  y,  r5-r8 

Apple: 
a,  x,  y 

Rectangle  draws  a  filled  rectangle  on  the  screen  as  determined  by  the 
coordinates  of  the  upper-left  and  lower-right  comers.  The  rectangle  is  filled  with 
the  current  8x8  (card-sized)  fill  pattern. 

The  8x8  pattern  within  the  rectangle  is  drawn  as  if  it  were  aligned  to  a  card 
boundary:  that  is,  the  bit-pattem  is  synchronized  with  (0,0),  and,  since  the 
patterns  are  8x8,  they  are  aligned  with  every  eighth  pixel  thereafter.  This  allows 
the  patterns  in  adjacent  or  overlapping  rectangles  to  line-up  regardless  of  the 
actual  pixel  positions. 

Rectangle  operates  by  calling  HorizontalLine  in  a  loop,  changing  the  bit- 
pattem  byte  after  every  line  based  on  the  current  8x8  fill  pattern. 

Because  all  GEOS  coordinates  are  inclusive,  framing  a  filled  rectangle  requires 
either  calling  FrameRectangle  after  calling  Rectangle  (and  thereby 
overwriting  the  perimeter  of  the  filled  area)  or  calling  FrameRectangle  with 
(Xi-l,y7-l)  and  (X2+l,y2+l)  as  the  comer  points. 


128: 


Under  GEOS  128,  or'ing  DOUBLE  W  into  theX7  andX2  parameters  will 
automatically  double  the  x-position  in  ^D-column  mode.  Or'ing  in  ADD1_W  will 


irgaBScaTTfcfne- 


automaticaUy  add  1  to  a  doubled  x-position.  (Refer  to  "GEOS  128  X-position  and 
Bitmap  Doubling  •  in  Chapter.@gr@  for  more  information.) 

See  also:       FrameRectangle,  SetPattern.  ImprintRectangle.  RecoverRectangle 
InvertRectangle.  *  ' 


ReDoMenu 


ReDoMenu  (Apple,  C64,  ci28) 


icon/menu 


Function: 
Parameters:  none 
Destroys: 
Description 


Reactivate  menus  at  the  current  level. 


Example: 
See  Also: 


assume  r0-rl5,  a,  x,  y 


ReDoMenu  is  used  by  the  application's  menu  event  handler  to  instruct  GEOS  to 
leave  all  menus  (including  the  current  menu)  open  when  control  is  returned  to 
MainLoop.  menuNumber  is  unchanged.  Keeping  the  current  menu  open 
allows  anotiier  selection  to  be  made  immediately. 

ReDoMenu  will  redraw  the  current  menu.  If  menu  event  routine  changes  the  text 
in  the  menu  (adding  a  selection  asterisk,  for  example),  a  call  to  ReDoMenu  will 
redraw  the  menu  with  the  new  text  wliile  leaving  the  menu  open  for  another 
selection. 


DoMenu,  GotoFirstMenu,  DoPreviousMenu. 
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RenameFile 


RenameFile  (Apple,  C64,  ci28) 


high-level  disk| 


Function: 
Parameters: 

Uses: 


Returns: 
Alters: 


Destroys: 


Renames  a  file  that  is  in  the  current  directory. 
r6 
rO 


OLDNAME  —  pointer  to  null-terminated  name  of  file  as  it  appean  on  the 
disk  (Apple  GEOS:  must  be  in  main  memory)  (word). 
NEWNAME  —  pointer  to  new  null-terminated  name  (Apple  GEOS:  must 
be  in  main  memory)  (word). 


curDrive 

Commodore: 
curType 

Apple: 

curVBlknot 

VBMchangedt 

numVBMBlkst 


GEOS  64  vl.3  and  later,  for  detecting  REU  shadowing. 


used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines:  applications  generally  don't  use. 
X       error  ($00  =  no  error). 


diskBlkBuf 
dirEntryBuf 

ComnKxlore: 
curDirHead 
dirlHeadt 
dirSHeadt 

Apple; 

curVBlkno^ 
VBMchangedt 


used  for  temporary  block  storage, 
old  directory  entry. 


BAM  updated  to  reflect  newly  freed  blocks. 
(BAM  for  1571  and  1581,drives  only) 
(BAM  for  1581  drive  only) 


used  by  VBM  cacheing  routines. 

set  to  FALSE  by  VBM  cacheing  routines  to  indicate  cached 
VBM  block  has  already  been  flushed 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
a,  y,  rl,  r4-r6. 


Description:   RenameFile  searches  the  current  directory  for  OLDFILE  and  changes  the  name 
string  in  the  directory  entry  to  NEWFILE. 

RenameFile  first  calls  FindFile  to  get  the  directory  entry  and  ensure  the 
OLDFILE  does  in  fact  exist.  (If  it  doesn't  exist,  a  FILE_NOT_FOUND  error 
is  returned.) 

The  directory  entry  is  read  in,  the  new  file  name  is  copied  over  the  old  file  name, 
and  the  directory  entry  is  rewritten.  The  date  stamp  of  the  file  is  not  changed,  but 
the  modification  date  stamp  of  the  directory  (Apple  GEOS  only)  is  updated. 
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RenameFile 


When  using  GetlstDirEntry  and  GetNextDirEntry  to  establish  the  old  file 
name,  do  not  pass  RenameFile  a  pointer  into  diskBlkBuf.  Copy  the  file  name 
from  diskBlkBuf  to  another  buffer  (such  as  dirEntryBuf)  and  pass  FreeFile 
the  pointer  to  that  buffer.  Otherwise  when  FreeFile  uses  diskBlkBuf  it  will 
corrupt  the  file  name.  . 

C64  &  C128:  Since  Conirnodorc  GEOS  does  not  support  a  hierarchical  file  system,  the  "current 
directory"  is  actually  the  entire  disk.  The  call  to  FindFile  also  reads  the  BAM  in 
from  disk. 

Apple:  Will  only  rename  a  file  in  the  current  directory.  To  rename  a  file  from  another 

directory,  the  application  must  change  directories  (refer  to  GoDirectory  for 
moving  to  another  directory). 

Example: 

See  also:       DeleteDir,  FreeDir,  FreeFile,  FreeBlock. 
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ReOpenDisk 


IReOpenPisk  (AppieT 


high-level  disk| 


Function: 

Parameters: 

Uses: 

Returns: 

Alters: 


Reopen  a  disk  to  the  most  recent  directory. 


Destroys: 
Description: 


Note: 


Example: 
See  also: 


none 

curDrive 

curDirTabLo 

curDirTabHi 


drive  that  disk  is  in. 
last  current  directory, 
last  current  directory. 


X       error  ($00  =  no  error). 

rS      pointer  to  disk  name  buffer  as  returned  from  GetPtrCurDkNm.  This  is 
a  pointer  to  one  of  the  Dr;cCurDkNm  arrays. 


DrxCurDkNm 
curDirHead 
curKBIkno 
sysDirBlkno 


totNumBlkst 

pathnameBur 

curVBIknot 

numVBMBIkst 

VBMchangedt 


current  disk  name  array  contains  disk  name. 

current  directory  header. 

block  number  of  current  directory's  key  block. 

block  number  of  /SYSTEM  directory.  If  system  directory 

not  found  on  disk,  then  this  number  is  block  of  the  root 

directory. 

total  number  of  blocks  in  volume, 
set  to  last  logged  directory, 
block  currently  cached, 
number  of  VBM  blocks  on  disk, 
set  to  FALSE. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
a,  y,  r0-r2,  r4. 

ReOpenDisk  reopens  a  disk  to  its  current  directory  (for  each  drive,  GEOS 
keeps  track  of  the  block  of  the  current  directory)..  ReOpenDisk  allows  an 
application  to  quickly  switch  back  and  forth  between  files  on  different  drives,  as 
is  often  the  case  when  an  application  and  its  data  are  on  different  disks.  It  saves 
the  application  from  calling  GoDirectory  every  time  drives  are  changed.  It 
otherwise  performs  the  same  initialization  as  OpenDisk. 

ReOpenDisk  assumes  the  user  has  not  switched  disks  since  the  last  time  the 
drive  was  accessed.  If  a  new  disk  is  placed  in  the  drive,  the  current  directory 
block  number  associated  with  the  drive  will  no  longer  be  valid  The  application 
may  want  remember  the  volume  name  when  first  opening  the  disk  and  then 
compare  the  volume  name  after  each  call  to  ReOpenDisk  with  the  original.  If 
they  match,  its  a  fairly  safe  assumption  that  the  disk  has  not  changed. 

Because  GEOS  uses  the  same  allocation  and  file  buffers  for  each  drive,  it  is 
important  to  close  all  files  and  update  tiie  VBM  (calling  PutVBM  if  necessary) 
before  accessing  another  disk. 


OpenDisk,  SetDevice. 
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ResetAlarm 


ResetAlarm  (Apple)  dock  dmerl 


Function:  Qock  driver  routine  to  disable  the  alamx 

Parameters:  none. 

Returns:  nothing. 

Alters:  alarmOn  $00 

Destroys:  assume  a,  x,  y,  r0-rl5. 

Description:  ResetSetAlarm  is  a  clock  driver  routine  for  disabling  an  alarm. 

See  also:  SetAlarm,  SetTimeDate,  Ciockint,  ReadCIock. 


CGNrtBE!NTt4L 
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ResetHandle 


ResetHandle  (C64,  cns)  internal  I 


Function:       Internal  routine  used  during  the  GEOS  boot  process. 
Parameters:  none. 
Returns:        does  not  return. 

Description:    ResetHandle  is  only  used  during  the  GEOS  boot  process.  It  is  not  useful  to 
applications  and  is  documented  here  only  because  it  exists  in  the  jump  table. 

See  also:  BootGEOS. 
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This  page  intentionally  left  blank  to  maintain  right/left  (verso/recto) 
page  ordering.  Final  version  will  correct  this. 


RestartProcess 


RestartProcess  (Apple,  C64,  ci28)  proccssi 


Function:  Reset  a  process's  timer  to  its  starting  value  then  unblock  and  unfreeze  the 
process. 

Parameters:    x       PROCESS  —  process  to  restart  (0  -  n-1,  where  n  is  the  number  of 

processes  in  the  table)  dbytc). 

Returns:        x  unchanged 

Destroys:  a 

Description:  RestartProcess  sets  a  process's  countdown  timer  to  its  initialization  value  then 
unblocks  and  unfreezes  it  Use  RestartProcess  to  initallj^  start  a  process  after  a 
call  to  InitProcesses  or  to  rewind  a  process  to  the  beginning  of  its  cycle. 

Note:  RestartProcess  clears  the  runable  flag  associated  with  the  process,  thereby 

losing  any  pending  call  to  the  process. 

RestartProcess  should  always  be  used  to  start  a  process  for  the  first  time 
because  InitProcesses  leaves  Ae  value  of  the  countdown  timer  in  an  unknown 
state. 

Example: 

See  also:       InitProcesses,  EnableProcess,  UnfreezeProcess,  UnblockProcess. 
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RestoreFontPata  (Apple) 


RestoreFontData 


text 


Function: 

Parameters: 

Returns: 

Destroys: 
Description: 

Example: 
See  also: 


Restore  internal  font  data  from  saveFontTab, 
none. 

curHeight 

baselineOffset 

cardDataPntr 

curlndexTable 

curSetWidth 

a,  X. 

RestoreFontData  reverses  the  effect  of  SaveFontData  by  restoring  the 
internal  font  variables  from  saveFontTab. 


SaveFontData. 
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RstrAppI 


RstrAppI  (Apple,  C64,  C128) 

Function:       Standard  desk  accessory  return  to  application. 

Parameters:  none. 

Uses:  curDrive. 

Returns:        never  retutrns  to  desk  accessory. 

Description:  A  desk  accessory  calls  RstrAppI  when  it  wants  to  return  control  to  the 
application  that  called  it.  RstrAppI  loads  the  swapped  area  of  memory  from  the 
SWAP  FILE,  restores  the  saved  state  of  the  system  from  the  internal  buffer, 
resets  the  stack  pointer  to  its  original  position,  and  returns  control  to  the 
application. 

It  is  the  job  of  the  desk  accessory  to  ensure  that  if  the  current  drive  (curDrive)  is 
changed  that  it  be  returned  to  its  original  value  so  that  RstrAppI  can  And 
SWAP  FILE.  Under  Apple  GEOS  it  is  not  necessary  to  save  the  current 
directory. 

Note:  If  a  disk  error  occurs  when  reading  in  SWAP  FILE,  the  remainder  of  the 

context  switch  (restoring  the  state  of  the  system,  etc.)  is  bypassed  and  control  is 
immediately  returned  to  the  caller  of  the  desk  accessory.  The  application  will  have 
only  a  moderate  chance  to  recover,  however,  because  the  area  of  memory  that  the 
desk  accessory  overlayed  may  very  well  include  the  area  where  the  jsr  to 
GetFile  or  LdDeskAcc  resides.  The  return,  therefore,  may  end  up  in  the 
middle  of  desk  accessory  code. 

Example: 

See  also:       StartAppl,  GetFile. 


high-level  disk 
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RstrFrmDialog 


RstrFrmPialog  (Apple,  C64,  cns)  dialog  box| 

Function:  Exits  from  a  dialog  box,  restoring  the  system  to  the  state  prior  to  the  call  to 
DoDlgBox. 

Parameters:  none. 

Returns:  Returns  to  point  where  DoDlgBox  was  called.  System  context  is  restored.  ROL 
contains  sysDBData  return  value. 

Uses:  sysDBData. 

Destroys:       assume  a,  x,  y,  rOH-rlS 

Description:  RstrFrmDialog  allows  a  custom  dialog  box  routine  to  exit  from  the  a  dialog 
box.  RstrFrmDialog  is  typically  called  internally  by  the  GEOS  system  icon 
dialog  box  routines.  However,  it  may  be  called  by  any  dialog  box  routine  to  force 
an  immediate  exit 

RstrFrmDialog  first  restores  the  GEOS  system  state  (context  restore)  and  then 
calls  indirecdy  through  recoverVector  to  remove  the  dialog  box  rectangle  firom 
the  screen.  The  routine  in  recoverVector  is  called  with  the  r2-r4  loaded  for  a 
call  to  RecoverRectangle.  By  default  recoverVector  points  to 
RecoverRectangle,  which  will  automatically  recover  the  foreground  screen 
from  the  background  buffer.  However,  if  the  application  is  using  background 
buffer  for  data,  it  will  need  to  intercept  the  recover  by  placing  the  address  of  its 
own  recover  routine  in  recoverVector.  If  there  is  no  shadow  on  the  dialog  box, 
then  recoverVector  is  only  called  through  once  with  r2-r4  holding  the 
coordinates  of  the  dialog  box  rectangle.  However,  if  the  dialog  box  has  a 
shadow,  then  recoverVector  will  be  called  through  two  ♦imes:  first  for  the 
patterned  shadow  rectangel  and  second  for  the  dialog  box  rectangle.  The 
application  may  want  to  special-case  these  two  recovers  when  recovering. 

If  recoverOnce  is  set  to  TRUE,  RstrFrmDialog  will  only  call  through 
recoverVector  once  as  if  there  were  no  shadow  box  (even  if  there  is  one). 
RstrFrmDialog  automatically  calls  RestoreSysRam. 

RstrFrmDialog  restores  the  sp  register  to  value  it  contained  at  the  call  to 
DoDlgBox  just  before  returning.  This  allows  RstrFrmDialog  to  be  called  witii 
an  arbitrary  amount  of  data  on  top  of  the  stack  (as  would  be  the  case  if  called  from 
within  a  subroutine).  GEOS  will  restore  the  stack  pointer  properly. 


DoDlgBox,  InitForDialog,  RestoreSysRam,  RecoverRectangle, 
RestoreFG. 
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Apple: 
Note: 

Example: 
See  also: 


SaveFG  (Apple) 


graphics/utility  I 


Function:       Saves  a  portion  of  the  foreground  screen  to  a  buffer. 

Parameters:    rO      FGSTRUCT — pointer  to  an  FG  data  structure  (word). 

rl      FGBUF  —  pointer  to  buffer  to  place  foreground  data  (word). 

Returns:        Buffer  pointed  to  by  FGBUF  contains  foreground  data  in  a  form  that 
RestoreFG  can  restore. 

Destroys:       a,x,  y,  rl-r6. 

Description:   SaveFG  saves  a  rectangular  area  of  the  foreground  screen  to  a  temporary  buffer. 

This  buffer  can  later  be  restored  to  the  foreground  screen  with  RestoreFG.  The 
SaveFG  and  RestoreFG  duo  allow  the  application  to  save  and  restore  areas  of 
the  foreground  screen  without  imprinting  them  to  the  background  buffer.  This 
capability  lets  the  application  use  the  background  buffer  for  data  while  still  using 
dialog  boxes  and  menus,  which  depend  on  recovering  from  the  background 
buffer.  The  application  need  only  saveFG  the  proper  areas  of  the  screen  prior  to 
putting  up  a  dialog  box  or  letting  a  menu  drop,  patch  into  recoverVector,  and 
RestoreFG  as  necessary. 

FGSTRUCT  points  to  an  FG  data  structure,  which  is  in  the  following  format: 

.word  XI  ;pixelx-position  of  left  edge 

.byte  Yl  ;pixel  y-position  of  top  edge 

.word  X2  ;pixel  x-position  of  right  edge  (XI  +  WIDTH) 

.byte  HEIGHT  ;pixel  height  (Y2  -  Yl) 


The  amount  of  data  stored  into  the  buffer  at  FGBUF  depends  on  die  size  of  the 
saved  region.  The  following  relationship  applies: 

bufBytes  =  HEIGHT  ♦  (Xl/7  -  X2/7  +1) 

Most  GEOS  applications  will  reserve  5,712  bytes  for  the  save  buffer,  which  will 
hold  the  largest  standard  dialog  box  or  about  three  levels  of  submenus. 

Note:  It  is  useful  to  set  recoverOnce  to  TRUE  when  using  SaveFG,  which  will 

cause  dialog  boxes  witii  shadows  to  only  call  through  recoverVector  once, 
rather  than  the  noraial  twice. 

Example: 

See  also:  RecoverFG. 
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SaveFile 


SaveFile  (Apple,  C64,  cns) 


high-level  diskj 


Function: 
Parameters: 


Uses: 


General  purpose  save  file  routine  that  will  create  a  GEOS  sequential  file  and  save 
a  region  of  memory  to  it  or  create  an  empty  GEOS  VLIR  file. 

r9  HEADER  —  pointer  to  GEOS  file  header  for  file.  The  first  two  bytes  of 
the  file  header  point  to  the  filename  (word). 

rlOL  DIRPAGE  —  GEOS  directory  page  to  begin  searching  for  fiee  directory 
slot;  each  directory  page  holds  eight  files  and  corresponds  to  one 
notepad  page  on  the  GEOS  deskTop.  The  first  page  is  page  one. 


curDrive 

year,  month,  day,  hours,  minutes 


for  date-stamping  file. 


Commodore: 

curType 

interleave^ 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing, 
desired  physical  sector  interleave  (usually  8);.  applications 
need  not  set  this  explicitly  —  will  be  set  automatically  by 
internal  GEOS  routines. 


Returns: 


Alters: 


Apple; 
RWbank 

curKBlkno 
curVBlknot 
VBMchangedt 
numVBMBikst 


source  bank  for  sequential  data  and  HEADER  (MAIN  or 
AUX). 

current  directory, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
X         error  ($00  =  no  error). 

r9        pointer  to  fileHeader,  which  contains  file  header  block  as  written  to 
disk. 

Commpdorg; 

r6        pointer  to  fileTrScTab,  which  contains  track/sector  table  for  the  file. 


dirEntryBuf 
diskBlkBuf 
curDirHead 

Commodore: 
fileTrScTab 


dir2Headt 
dir3Headt 


contains  newly-built  directory  entry. 

used  for  temporary  storage. 

this  buffer  contains  die  current  directory  header. 


Contains  track/sector  table  for  file  as  returned  from 
BlkAUoc.  The  track  and  sector  of  the  file  header  block  is  at 
fileTrScTab+O  and  fileTrScTab+1.  The  end  of  the  table 
is  marked  with  a  track  value  of  $00. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


Applg: 
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SaveFile 


INDEXBLOCKBUFt     index  block  for  chain  as  created  by  BlkAlloc  (in 

auxiliary  memory;  see  BlkAlloc  for  information  on 
accessing  it). 

^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 

Destroys:  Commodore: 
a,  y,  r0-r8. 


Apple: 

a,  y,  rl-r8. 

Description:  SaveFile  is  the  most  general  -pupose  write  data  type  routine  in  GEOS.  It  creates 
a  new  file,  either  sequential  or  VLIR.  If  the  file  is  a  sequential  file,  it  will  write 
out  the  range  of  memory  specified  in  the  header  to  disk.  If  the  file  is  a  VLIR  file, 
it  will  create  an  empty  file  (just  a  file  header  and  an  index  table;  all  records  in  the 
index  table  are  marked  as  unused). 

Not  only  does  the  file  header  pointed  to  by  HEADER  act  as  a  prototype  for  the 
file,  it  also  holds  all  the  information  needed  to  create  the  file.  This  includes  the  file 
type  (SEQ  or  VLIR)  and  other  pertinent  information,  such  as  the  start  and  end 
address,  which  are  used  when  creating  a  sequential  file.  The  file  header  pointed  to 
by  HEADER  has  one  element,  however,  that  is  changed  before  it  is  written  to 
disk:  the  first  word  of  the  fileheader  points  to  a  null-terminated  filename  string. 
SaveFile  patches  this  word  in  its  own  copy  in  fileHeader  before  it  is  written  to 
disk. 

SaveFile  calls  SetGDirEntry  and  BlkAlloc  to  construct  the  basic  elements  of 
the  file,  then  calls  WriteFile  to  put  die  data  into  it.  After  the  file  is  written,  the 
BAMA^BM  is  written  to  disk  (PutDirHead  under  Commodore  GEOS; 
PutVBM  under  Apple  GEOS.) 

Example: 


See  also:        GetFile,  GpenRecordFile. 
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SaveFontData 


SaveFontPata  (Apple) 


text! 


Function: 
Parameters: 
Returns: 
Uses: 


Destroys: 
Description: 

See  also: 
Example: 


Save  internal  font  data  to  saveFontTab. 

none. 

nothing. 

curHeight 

baselineOffset 

cardDataPntr 

curlndexTable 

curSetWidth 

a,  X. 

SaveFontData  saves  the  internal  font  variables  to  the  area  at  saveFontTab. 
This  allows  a  font  to  be  temporarily  changed  and  then  restored.  saveFontTab  is 
FONTLEN  bytes  long. 

RestoreFontData. 
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SetAlarm 


SetAlarm  (Apple) 


clock  driver 


Function:       Qock  driver  routine  to  set  the  clock's  alarm  time. 

Parameters:    rOL      HOUR  —  hour  (0-23)  (byte), 

rOH      MINUTE  —  minute  (0-59)  (byte). 

Returns:  nothing. 

Alters:  alarmOn  %10000000  (alarm  enabled  but  not  triggered). 

Destroys:       assume  a,  x,  y,  r0-rl5. 

Description:    SetAlarm  is  a  clock  driver  routine  for  setting  a  new  alarm  time.  Most  clock 
drivers  do  no  error  checking  on  the  parameters  and  expect  valid  values. 

Note:  To  be  sure  the  alarm  is  triggered  correcdy,  disable  interrupts  around  the  call  to 

SetAlarm. 

See  also:       ResetAIarm,  SetTimeDate,  Clocklnt,  ReadClock. 
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SetDevice 


SetDevice  (C64,  cns) 


high'level  disk| 


Function: 
Parameters: 

Uses: 

Returns: 

Alters: 

Destroys: 
Description: 


Note: 


Establish  communication  with  a  new  peripheral  (disk  or  printer). 

a  DEVNUM  —  DRIVE^A  through  DRIVE  D  for  disk  drives, 
PRINTER  for  serial  pnhtcr,  or  any  other  valid  serial  device  bus 
address  (byte). 

curDevice  currcndy  active  device. 

X         error  ($00  =  no  error). 


curDevice 

curDrive 

curType 


a.  y. 


new  current  device  number. 

new  current  drivcnumber  if  device  is  a  disk  drive. 

GEOS  vl.3  and  later:  current  drive  type  (copied  from 

driveType  table). 


SetDevice  changes  the  currcndy  active  Commodore  device  and  is  used  primarily 
to  switch  from  one  disk  drive  to  another.  SetDevice  also  allows  a  printer  driver 
to  gain  access  to  the  serial  bus. 

Each  I/O  device  has  an  associated  device  number  that  distinguishes  its  I/O  from 
the  I/O  of  other  devices.  At  any  given  time  only  one  device  is  active.  The  active 
device  is  called  the  current  device  and  to  change  the  current  device  an  application 
calls  SetDevice. 

Because  SetDevice  was  originally  designed  to  switch  between  serial  bus 
devices,  DEVN^Af  reflects  the  architecture  of  Commodore  serial  bus:  disk  drives 
arc  numbered  8  through  1 1  and  the  printer  is  numbered  4.  However,  not  all  I/O 
devices  are  actual  serial  bus  peripherals.  A  RAMdisk,  for  example,  uses  a  special 
device  driver  to  make  a  cartridge  port  RAM-expansion  unit  emukte  a  Commodore 
disk  drive.  SetDevice  switches  between  these  devices  just  as  if  they  were  daisy- 
chained  off  of  the  serial  bus. 

Commodore  GEOS  up  through  vl.2  supports  two  disk  devices,  DRIVE  A  and 
DRIVE  B.  Commodore  GEOS  vl.3  and  later  supports  up  to  four  disk  devices, 
DRIVE^A  through  DRIVE^D,  within  the  Kemal  disk  routiines  but  not  from  the 
dcskTopT  (The  current  version  of  the  deskTop  will  never  pass  numDrives  with 
a  value  greater  than  two.)  GEOS  always  addresses  the  first  drive  as  DRIVE^A, 
the  second  as  DRIVE_B,  and  so  on  regardless  of  the  physical  device  settings? 

Because  most  printers  attach  to  the  Commodore  through  the  serial  port,  printer 
drivers  wUl  call  SetDevice  with  a  DEVNUM  value  of  PRINTER  to  make  the 
printer  the  active  device. 

SetDevice  calls  ExitTurbo  to  ensure  that  the  old  device  is  no  longer  actively 
sensing  the  serial  bus  then  rearranges  the  device  drivers  as  necessary  to  make  the 
new  device  {DEVNUM)  the  current  device.  Witii  more  than  one  type  of  device 
attached  (e.g.,  a  1541  and  a  1571),  Commodore  GEOS  must  switch  the  internal 
device  drivers,  making  die  the  driver  for  die  selected  device  active.  GEOS  stores 
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SetDevice 


inactive  device  drivers  in  the  Conunodore  128  back  RAM  and  in  special  system 
areas  in  an  REU.  For  these  reasons  it  is  important  that  Commodore  GEOS 
applications  use  SetDevice  to  change  the  active  device.  An  application  should 
never  direcdy  modify  curDrive  or  curDevice. 

Apple:  SetDevice  does  not  exist  in  Apple  GEOS  because  die  task  of  switching  between 

devices  is  not  complicated  by  daisy-chained  I/O  devices  and  inactive  device 
drivers  (as  it  is  on  the  Commodore  computers).  To  specify  a  new  disk  drive, 
store  the  new  drive  number  diiecdy  into  curDrive. 

To  make  porting  disk  routines  easier,  the  following  Apple  equivalent  of 
SetDevice  can  be  used: 

.if     (APPLE)  /Apple  GEOS  SetDevice  equivalent 

SetDevice: 

sta  curDrive        ;make  the  requested  drive  current 

Idx  #NO_ERROR       ;and  return  a  good  status 

rts 

•endif 

See  also:       OpenDisk,  ChangeDiskDevice. 
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SetGDirEntry  (Apple,  C64,  cus) 


mid-levd  disk 


Function:  Builds  a  system  specific  directory  entry  from  a  GEOS  file  header,  date-stamps  it, 
and  writes  it  out  to  the  current  directory.  Apple  GEOS  version  will  also  create  and 
write  out  subdirectories. 

Parameters:    rlOL     DIRPAGE  —  directory  page  to  begin  searching  for  free  slot;  each 

directory  page  holds  eight  files  and  corresponds  to  one  notepad  page  on 
the  GEOS  deskTop.  The  first  page  is  page  one. 

r2        NUMBLOCKS  —  number  of  blocks  in  file  (word). 

r6        TSTABLE  —  pointer  to  a  track/sector  list  of  unused  blocks  (unused  but 

allocated  in  the  BAM),  usually  a  pointer  to  fileTrScTab;  BlkAUoc 

can  be  used  to  build  such  a  list  (word). 
r9        FILEHDR — pointer  to  GEOS  file  header  (word). 


Apple; 

r2        NUMBLOCKS  —  number  of  blocks  in  file  or  $(XXX)  to  create  a 

subdirectory  (word). 
r6        INDXBLK  —  If  creating  a  file:  block  number  of  sequential-file  index 

block  or  VLIR  master  index  block.  If  creating  a  subdirectory:  key  block 

of  subdirectory  (word). 
r7        FILEB YTES  —  number  of  bytes  in  file  (word). 
r8        HDBLKNUM  —  block  number  of  this  file's  header  block  (word). 
r9        FILEHDR — if  creating  a  file,  pointer  to  GEOS  file  header,  if  creating  a 

subdirectory,  pointer  to  16-character  max.  null-terminated  name  for 

subdirectory  (16  characters  including  NULL)  (must  be  in  main 

memory)  (word). 


Uses: 


curDrive 

year,  month,  day,  hours,  minutes 


for  date-stamping  file. 


curType 

curDirHead 

dir2Headt 

dir3Headt 

interleave^ 


GEOS  64  vl.3  and  later,  for  detecting  REU  shadowing, 
this  buffer  must  contain  die  current  d^ectory  header. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 

desired  physical  sector  interleave  (usually  8);.  applications 
need  not  set  this  explicitiy  —  will  be  set  automatically  by 
internal  GEOS  routines.  Only  used  when  new  directory 
block  is  allocated 


Returns: 


Apple: 

curKBIkno 
curVBlknot 
VBMchanged^ 
numVBMBlkst 


cunent  directory, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
X         error  ($(X)  =  no  error). 
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Commodore: 

r6  pointer  to  first  non-reserved  block  in  track/sector  table  (SetGDIrEntry 
reserves.one  block  for  the  file  header  and  a  second  block  for  the  index 
table  if  the  file  is  a  VLIR  file). 


Appig; 
rl 

rlOL 
rlOH 


block  number  that  directory  entry  was  added  to. 
directory  page  actually  used. 

unused  directory  entry  within  block  in  diskBIkBuf.  There  are  13 
directory  entries  per  ProDOS  block,  numbered  1-13. 


Alters: 


Destroys: 


dirEntryBuf 
diskBIkBuf 

Commodore: 

a,  y,  rO-rS,  r7-r8. 


contains  newly-built  directory  entry, 
used  for  temporary  storage  of  the  directory  block. 


Commodore: 

a,  y,  rl,  r3-r5,  r7-r8. 

Description:  SetGDirEntry  calls  BIdGDirEntry  to  build  a  system  specific  directory  entry 
form  the  GEOS  file  header,  date-stamps  the  directory  entry,  calls 
GetFreeDirBlk  to  find  an  empty  directory  slot,  and  writes  the  new  directory 
entry  out  to  disk.  The  Apple  version  of  SetGDirEntry  can  also  be  used  to  create 
subdirectory  entries  by  passing  a  NUMBLOCKS  value  of  $0000. 

Most  applications  will  create  new  files  by  calling  SaveFile  and  new 
subdirectories  by  calling  MakeSubDir.  Both  these  routines  call  SetGDirEntry 
as  part  of  their  normal  processing. 


Example: 
See  also: 


BIdGDirEntry . 
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SetGEOSDisk  (C64,  cns) 


high-level  disk] 


Function: 


Convert  Commodore  disk  to  GEOS  format. 


Parameters:  none. 


Uses: 

Returns: 
Alters: 


curDrive 
curType 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing, 
error  ($00  =  no  error). 


curDirHead        directory  header  is  read  from  disk. 
dir2Headt  (BAM  for  1571  and  1581  drives  only) 

dir3Headt  (BAM  for  1581  drive  only) 


Destroys:       a,  y,  rOL,  rl,  r4-r5. 


Description: 


Apple: 
Example: 
See  also: 


SetGEOSDisk  converts  a  standard  Commodore  disk  tinto  GEOS  format  by 
writing  the  GEOS  ID  string  to  the  directory  header  (at  OFF^GEOS  ID)  and 
creating  an  off-page  directory  block.  An  application  can  call  SetGEOSCisk  after 
OpenDisk  returns  the  isGEOS  flag  set  to  FALSE.  Typically  the  user  is 
prompted  before  the  conversion. 

SetGEOSDisk  expects  the  disk  to  have  been  previously  opened  with 
OpenDisk.  It  first  calls  GetDirHead  to  read  the  directory  header  into  memory 
then  calls  CalcBlksFree  to  to  see  if  there  is  block  available  for  the  off-page 
directory  (if  there  isn't,  an  INSUFFICIENT^SPACE  error  is  returned). 
SetNextFree  is  then  called  to  allocate  the  off-page  directory  block.  The  off-page 
directory  block  is  written  with  empty  directory  entries  and  a  pointer  to  it  is  placed 
in  the  directory  header  (at  OFF^OP  TR  SC).  Finally  PutDirHead  is  called  to 
write  out  the  new  BAM  and  directoryTieader. 

All  ProDOS  disks  are  already  GEOS  compatible. 


ChkDkGEOS. 
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SetLdVars  (Apple) 


mid-level  disk  I 


Function: 
Parameters: 


Sets  the  internal  "Ld"  variables  (those  used  by  LdAppI,  LdDeskAcc,  and 
LdFile). 

rOL  LOAD.OPT: 

bitO:  0  load  at  address  specified  in  file  header,  application  will  be 
started  autmadcally 
1  load  at  address  in  r7;  application  will  not  be  started 
automatically, 
bit?:  0  not  passing  a  data  file. 

1  r2  and  r3  contain  pointers  to  disk  and  data  file  names, 
bit  6:  0  not  printing  data  file. 

printing  data  file;  application  should  print  file  and  exit 
r7        LOAD.ADDR  —  optional  load  address,  only  used  if  bit  0  of 

LOADJ)PT  is  set  (word). 
r2        DATA^DISK  —  only  valid  if  bit  7  or  bit  6  oiWADJ)PT  is  set:  pointer 
to  name  of  the  disk  tiiat  contains  the  data  file,  usually  a  pointer  to  one  of 
the  DrxCurDkNm  buffers  (word). 

DATA^FILE  —  only  valid  if  bit  7  or  bit  6  olLOADJ)PT  is  set:  pointer 
to  name  of  the  data  file  (word). 
RECVR^OPTS  (byte). 


Returns: 

Destroys: 

Description: 

Note: 


r3 

rlOL 

nothing. 


SetLdVars  sets  the  internal  load  variables  from  GEOS  pseudoregisters. 
GetFile,  LdApplic,  LdDeskAcc,  and  LdFile  call  SetLdVars  as  necessary. 
Most  applications  will  not  need  to  call  it  direcdy. 

LdDeskAcc  does  not  properly  set  the  internal  "Ld**  variables  when  it  is  called 
direcdy  (as  opposed  to  indirecdy  through  GetFile,  in  which  case  the  variables 
are  set  properly).  SetLdVars  may  be  used  to  properly  set  the  internal  "Ld" 
variables  prior  to  calling  LdDeskAcc. 


See  also:  GetLdVars. 
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SetMode 


SetMode  (Apple) 


printer  driver  | 


Function:       Set  printer  mode. 

Parameters:    rO-r2L  MODE  —  flags  for  possible  printer  modes  and  capabilities  (five  bytes). 
Returns:        x         STATUS  —  printer  error  code;  $00  =  no  eiror  (byte) 
Destroys:       assume  r0-r4. 

Description:  SetMode  allows  an  application  to  access  special  printer  capabilities.  Features  are 
selected  through  five  MODE  bytes.  The  bits  in  the  MODE  bytes  correspond  to  the 
list  of  available  features  returned  by  GetMode. 

SetMode  operates  intelligently.  It  first  compares  the  requested  MODE  setting 
against  the  current  state  of  the  printer.  If  a  bit  setting  is  different  and  the  driver 
supports  the  associated  feature,  then  the  proper  codes  are  sent  to  the  printer  to 
establish  the  new  mode. 

TheA/OPgVaiyes; 


bit 

description 

b7 

^underiine. 

b6 

tbold. 

b5 

reverse. 

M 

^italic. 

b3 

outline. 

b2 

tsuoerscript 

bl 

^subscript 

bO 

reserved  for  future  use. 

(text  density  selection) 
bit  description 

b7 

^pica  type  (10  cpi). 

b6 

^elite  type  (12  cpi). 

b5 

^condensed  type  (16  cpi). 

b4 

^proportional  type. 

b3 

^double  heishL 

b2 

^f-heisht 

bl 

^eisht  lines  per  inch  vertical  density. 

bO 

^six  lines  per  inch  vertical  density. 

rOH: 


rlL: 


(miscellaneous  features) 
bit  description 
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b7 

print  red  or  masenta. 

b6 

print  yellow. 

b5 

print  blue  or  cyan. 

M 

^expanded  (double-widih)  type. 

b3 

^NLO  (near  letter  quality)  type. 

b2 

reserved  for  future  use. 

bl 

reserved  for  future  use. 

bO 

reserved  for  future  use. 

(internal  font  selection) 
bit  description 

b7 

font?. 

b6 

font  6. 

b5 

fonts. 

b4 

font  4. 

b3 

font  3. 

b2 

font  2  (Roman?). 

bl 

font  1  (Helvetica?). 

bO 

font  0  (Courier?). 

(hoTizontal  graphics  density  selection) 
bit  description 

b7 

60  dpi. 

b6 

^SOdpi. 

b5 

90  dpi. 

b4 

120  dpi. 

b3 

180  dpi. 

b2 

300  dpi. 

bl 

360  dpi. 

bO 

reserved  for  future  use. 

^This  feature  implemented  in  most  Berkeley  Softworks  printer  drivers. 


Note:  Most  printer  drivers  only  support  a  small  subset  of  these  features  even  if  the 

printer  they  are  driving  supports  more. 

Example: 

See  also:       GetMode,  SetNLQ. 
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ISetMouse  (Ci28) 


input  driver 


Function: 


Input  device  scan  reset. 


Parameters: 


none. 


Returns: 


nothing 


Destroys:       assume  a,  x,  y,  r0-rl5 

Description:   GEOS  128  calls  SetMouse  during  Interrupt  Level,  immediately  after  the 


keyboard  is  scanned  for  a  new  key,  to  reset  the  pot  (potentiometer)  scanning  lines 
so  that  they  will  recharge  with  the  new  value  of.  It  is  primarily  of  use  with  the 
Commodore  1351  mouse,  which  requires  having  the  pot  lines  reset  regularly. 
Other  input  drivers  will  have  a  SetMouse  routine  that  merely  performs  an  rts. 
An  application  should  never  need  to  call  SetMouse. 


See  also:       SIowMouse,  UpdateMouse,  InitMouse,  KeyFilter. 
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SetMsePic  (Apple,  cns) 


sprite/mouse! 


Function: 
Parameters: 

Returns: 

Destroys: 

Description: 


Note: 
Example: 


Uploads  and  pre-shifts  a  new  mouse  picture  for  the  software  sprite  handler. 

rO      MSEPIC  —r  pointer  to  32  bytes  of  mouse  sprite  image  data  or  one  of  the 
following  special  codes: 

ARROW  Arrow  pointer  (Apple  and  C128) 

HOURGLASS        Busy  (Apple  only) 

nothing. 

a,  X, y, r0-rl5 

The  software  sprite  routines  used  by  GEOS  128  in  80-column  mode  and  Apple 
GEOS  treat  the  mouse  sprite  (sprite  #0)  differently  than  the  other  sprites.  Sprite 
#0  is  optimized  and  hardcoded  to  provide  reasonable  mouse-response  while 
minimizing  the  flicker  typically  associated  with  erasing  and  redrawing  a  fast- 
moving  object.  The  mouse  sprite  is  limited  to  a  16x8  pixel  image.  The  image 
includes  a  mask  of  the  same  size  and  both  are  stored  in  a  pre-shifted  form  within 
internal  GEOS  buffers.  For  these  reasons,  a  new  mouse  picture  must  be  installed 
with  SetMsePic  (as  opposed  to  a  normal  DrawSprite).  SetMsePic  pre-shifts 
the  image  data  and  lets  the  soft-sprite  mouse  routine  know  of  the  new  image. 

SetMsePic  accepts  one  parameter:  a  pointer  to  the  mask  and  image  data  or  a 
constant  value  for  one  of  the  predefined  shapes.  If  a  user-defined  shape  is  used, 
the  data  that  MSEPIC  points  to  is  in  the  following  fonnat: 


16  bytes 


16  bytes 


16x8  "cookie  cutter"  mask.  Before  drawing  the  software  mouse  sprite, 
GEOS  and*s  this  mask  onto  the  foreground  screen.  Any  zero  bits  in  the 
mask,  clear  the  corresponding  pixels.  One  bits  do  not'affect  the  screen. 


16x8  sprite  image.  After  clearing  pixels  with  the  mask  data,  the  sprite 
image  is  or*ed  into  the  area.  Any  one  bits  in  the  sprite  image  set  the 
corresponding  pixels.  Zero  bits  do  not  affect  the  screen. 


GEOS  treats  the  each  16-byte  field  as  8  rows  of  16  bits  (two  bytes  per  row). 
SetMsePic  calls  HideOnlyMouse. 


Put  up  a  new  mouse  picture 


ArrowUp: 

LoadW       rO,  #DnArrow  ; point  at  new  image 

jsr  SetMsePic  ; install  it 

Its 

;macro  to  store  a  word  value  in  high/low  order 
.macro  , HILO  word 

.byte        J  word, [word 

•  endm 

/Mouse  picture  definition  for  down-pointing  arrow 
DnArrow: 
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;mas)c 


HILO  %1111111110000000 

HILO  %1111111001111110 

HILXD  %0001100111111001 

HILO  %0110011111100111 

HILO  %0111111110011111 

HILO  %01H111110011111 

HILO  %0111111111101111 

HILO  %0000000000001111 


; image 

HILO  %0000000000000000 

HILO  %0000000001111110 

HILO  %0000000111111000 

HILO  %0110011111100000 

HILO  %0111111110000000 

HILO  %0111111110000000 

HILO  %0111111111100000 

HILO  %0000000000000000 

See  also:       TempHideMouse,  DrawSprite. 
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SetNewMode  (Ci28) 


graphicsj 


Function:       Changes  GEOS  128  from  40-column  mode  to  SO-column  mode,  or  vice-versa. 

Parameters:    graphMode        .  GRMODE  —  new  graphics  mode  to  change  to: 

40-column:  GR  40 
80-column:  GR^80 

Returns:  nothing. 
Destroys:       a,  x,  y,  r0-rl5. 

Description:   SetNewMode  changes  the  operating  mode  of  the  Commodore  128. 
|40-column  mode  (graphMode  —  GR  40)1 

1:  8510  clock  speed  is  slowed  down  to  IMhz  because  VIC  chip  cannot  operate 
at2Mhz. 

2:  rightMargin  is  set  to  319. 

3:  UseSystemFont  is  called  to  begin  using  the  40-column  font 

4:  40-column  VIC  screen  is  enabled. 

5:  80-column  VDC  screen  is  set  to  black  on  black,  effectively  disabling  it 


Example: 


180-column  mode  (graphMode  ==  GR  sUTl 
1:  8510  clock  speed  is  raised  to  2Mhz. 
2:  rightMargin  is  set  to  639. 

3:  UseSystemFont  is  called  to  begin  using  die  80-column  font 
4:  40-column  VIC  screen  is  disabled 
5:  80-column  VDC  screen  is  enabled 


ChangeMode : 
jsr 
Ida 
eor 
jsr 
jsr 
rts 

GREYPAT 

GreyScreen: 
jsr 
.byte 
.byte 


GreyScreen 

graphMode 

«%10000000 

SetNewMode 

GreyScreen 


;grey  out  old  screen 
/switch  mode  by  flipping 
; 40/80  bit 

;and  calling  SetNewMode 
;grey  out  new  screen 
;exit 

;grey  pattern  to  use 


i_GraphicsString 

NEWPATTERN, GREYPAT    ;set  to  grey  pattern 
MOVEPENTO  ;put  pen  in  upper  left 
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.word  0  »x 

.byte  0  ;y 

.byte  RECTANGLETO  ;grey  out  entire  screen 

.word  (SC_40_WIDTH-1) 1 DOUBLE_W| ADD1_W 

.byte  SC_PIX_HEIGHT 

.byte  NULL 

rts 
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SetNextFree  (Apple,  C64,  ci28) 


mid-level  disk  I 


Function: 

Parameters: 

Uses: 


Returns: 
Alters: 


Destroys: 


Description: 


Search  for  a  nearby  free  block  and  allocate  it. 

r3        block  (Commodore  track/sector)  to  begin  search  (woid). 

curDrive 


Cpmrnodorp; 

curDirHead 

dir2Headt 

dirSHeadt 

interleave^ 


Apple: 

curVBlknot 
VBMchangedt 
numVBMBlkst 
totNumBlockst 


this  buffer  must  contain  the  current  directory  header. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 

desired  physical  sector  interleave  (usually  8);.  applications 
need  not  set  this  explicidy  —  will  be  set  automatically  by 
internal  GEOS  routines. 


used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
for  detecting  last  block  on  disk. 


^used  internally  by  GEOS  disk  routines;  explications  generally  don't  use. 

X  error  ($00  =  no  error). 

r3        block  (Commodore  track/sector)  allocated. 


Commp<[OTP; 
curDirHead 
dir2Headt 
dirSHeadt 

Apple: 

curVBIknot 
VBMchangedt 


BAM  updated  to  reflect  newly  allocated  block. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


used  by  VBM  cacheing  routines. 

set  to  TRUE  by  VBM  cacheing  routines  to  indicate  cached 
VBM  block  has  changed  and  needs  to  be  flushed 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 

Commodore: 

a,  y,  r6-r7,  r8H. 

Apple; 

a,  y,  r6,  r7,  rSH. 

Given  the  current  block  as  passed  in  r3,  SetNextFree  searches  for  the  next  free 
block  on  the  disk.  The  "next"  free  block  is  not  necessarily  adjacent  to  the  previous 
block  because  SetNextFree  may  interleave  the  blocks.  Proper  interleaving 
aUows  the  drive  to  read  and  write  data  as  fast  as  possible  because  it  minimizes  the 
time  the  drive  spends  waiting  for  a  block  to  spin  under  the  read/write  head.  It 
means,  however,  that  sequential  data  blocks  may  not  occupy  adjacent  blocks  on 
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the  disk.  As  long  as  an  application  is  using  the  standard  GEOS  file  structuies,  this 
interleaving  should  not  be  apparent 

After  determining  the  ideal  sector  from  any  interleave  calculations,  SetNextFree 
tries  to  allocate  the  block  it  if  it  is  unused.  If  the  block  is  used,  SetNextFree 
picks  another  nearby  sector  (jumping  to  another  track  if  necessary)  and  calls  tries 
again.  This  process  continues  until  a  block  is  actually  allocated  or  the  end  of  the 
disk  is  reached,  whichever  comes  first.  If  the  end  of  the  disk  is  reached,  an 
INSUFFICIENT^SPACE  error  is  returned. 

Notice  that  SetNextFree  only  searches  for  free  blocks  starting  with  the  current 
block  and  searching  towards  the  end  of  the  disk.  It  does  not  backup  to  check 
other  areas  of  the  disk  because  it  assumes  they  have  abeady  been  filled.  (Actually, 
under  Commodore  GEOS,.SetNextFree  will  backtrack  as  far  back  as  beginning 
of  the  current  track  but  will  not  go  to  any  previous  tracks.).  Usually  this  is  a  safe 
assumption  because  SetNextFree  is  called  by  BlkAlIoc,  which  always  begins 
searching  for  free  blocks  from  the  beginning  of  the  disk. 

It  is  conceivable,  however,  that  an  application  might  want  to  implement  an 
AppendRecord  function  (or  something  of  that  sort),  which  would  append  a 
block  of  data  to  an  already  existing  VLIR  record  without  deleting,  reallocating, 
and  then  rewriting  the  record  like  WriteRecord. 

In  order  to  maintain  any  interleave  from  the  last  block  in  the  record  to  the  new 
block,  the  AppendRecord  routine  passes  the  track  and  sector  of  the  last  block  in 
the  record  to  SetNextFree.  SetNextFree  will  start  searching  from  this  block. 
If  a  free  block  cannot  be  found,  an  INSUFFICIENT  SPACE  error  is 
returned.  Since  SetNextFree  only  searched  from  the  currenttlock  to  the  end  of 
the  disk,  the  possiblility  exists  that  a  free  block  lies  somewhere  on  a  previous, 
still  unchecked  disk  area.  The  following  alternative  to  SetNextFree  will 
circumvent  this  problem: 

My Set Next Free: 

;Look  for  a  free  block  starting  at  the  current  block 

;so  that  we  continue  the  interleave  if  possible 

jsr  SetNextFree   ;  look  for  block  to  allocate 

cpx  #INSOFFICENT_SPACE    ; check  for  no  blocks 

beq  10$  /start  from  beginning  if  none 

rts  ;exit  on  any  other  error  or 

; valid  block  found. 

;We  got  an  insufficient  space  error.  Start  the  search 

; again  from  the  beginning  of  the  disk. 

10$: 


APPLE 

LoadW 

r3,#0 

/start  at  block  0 

;CBM 

LoadB 

r3H,#0 

/always  sector  0 

Idx 

#1 

/assume  track  1 

Idy 

curDrive 

/but  special  case  1581 

Ida 

driveType-8,y 

/because  of  outer /inner  track 

and 

#$0f 

/searching  scheme 

cmp 

#DRV_1581 

bne 

20$ 

/branch  if  not  1581 

Idx 

#39 

/1581  counts  down  on  inner  (39-1) 

/then  up  on  outer  (41-80) 
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stx  r3L  /track  number 

•endif 

jmp  SetNextFree  ;go  search,  let  it  return 

C64  &  C128:  SetNextFree  uses  the  value  in  interleave  to  establish  the  ideal  next  sector.  A 
good  interleave  will  arrange  successive  sectors  so  as  to  minimize  the  time  the 
drive  spends  stepping  the  read/write  head  and  waiting  for  the  desired  sector  to 
spin  around.  The  value  in  interleave  is  usually  set  by  the  Configure  program 
and  internally  by  GEOS  disk  routines.  The  application  will  usually  not  need  to 
worry  about  the  value  in  interleave. 


Because  Commodore  disks  store  the  directory  on  special  tracks,  SetNextFree 
will  automatically  skip  over  these  special  tracks  unless  r3L  is  started  on  one  of 
these  tracks,  in  which  case  SetNextFree  assumes  that  this  was  intentional  and  a 
block  on  the  directory  track  is  allocated.  (This  is  exactly  how  GetFreeDirBlk 
operates.)  The  directory  blocks  for  various  drives  can  be  determined  by  the 
following  constants: 


1S81 

DIR 

1581  TRACK 

(one  track) 

1541 

DIR 

TRACK 

(one  track) 

1571 

DIR 

TRACK 

(two  tracks) 

DIR" 

:track+n_tracks 

SetNextFree  does  not  automatically  write  oiit  the  BAM.  See  PutDirHead  for 
more  information  on  writing  out  the  BAM 


Apple:  The  Apple  version  of  SetNextFree  does  no  interleave  calculations  because 

ProDOS  devices  handle  physical  interleaving  when  they  map  block  numbers  to 
physical  sectors.  SetNextFree  on  the  Apple  merely  increments  the  block 
number. 

SetNextFree  does' not  automatically  flush  tiie  VBM  cache.  3ee  PutVBM  for 
more  information  on  flushing  the  cache. 

Example: 

See  also:       AllocateBIock,  FreeBiock,  BlkAlloc. 
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SetNLQ 


SetNLQ  (C64,  C128) 


printer  driver  | 


Function:  Enter  high-quality  printing  mode. 
Parameters:  rl 


WORKBUF  —  pointer  to  a  640-byte  work  buffer  for  use  by  the  printer 
driver  (word). 


Returns:  nothing. 

Destroys:       assume  a,  x,  y,  r0-rl5. 

Description:  SetNLQ  sends  the  appropriate  control  codes  to  place  the  printer  into  high-quality 
print  mode  (as  opposed  to  the  default  draft  mode).  SetNLQ  is  called  after 
StartASCn  has  been  called  to  enable  text  output 


See  also: 


StartASCII,  PrintASCII,  SetMode. 
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SetPattern 


SetPattern  (Apple,  C64,  cns) 


graphics] 


Function: 

Parameters: 

Returns: 

Alters: 

Destroys: 

Description: 


Apple: 

Example: 
See  also: 


Set  the  current  fill  pattern. 

a       GEOS  system  pattern  number  (must  be  between  0  and  3 1 )  (byte), 
nothing. 

curPattern  Contains  an  address  pointing  to  the  eight-byte  pattern, 

a 

Sets  the  current  fill  pattern.  There  are  34  system  patterns  (numbered  0-33)  in 
GEOS  64  and  GEOS  128;  Apple  GEOS  adds  a  35th,  user-defined  pattern 
(number  34).  Unfortunately,  SetPattern  will  only  work  correcdy  with  patterns 
numbered  0-31.  To  access  higher  number  patterns,  call  SetPattern  with  a  value 
of  31  and  add  8  to  curPatttern  to  access  pattern  32,  add  16  to  access  pattern  33, 
and  so  on. 

Although  curPattern  will  contain  a  valid  address,  it  is  an  address  in  auxiliary- 
high  memory,  and  this  memory  bank  is  all  but  inaccessible  to  user  applications. 
Use  GetPattern  and  SetUserPattern  to  access  the  pattern  data. 


GetPattern,  SetUserPattern. 
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SetTimeDate 


SetTimeDate  (Apple) 


clock  driver  I 


Function:       Qock  driver  routine  to  set  the  clock's  time  and  date. 

Parameters:    rOL  YEAR  — ^.current  year  (calendar  year  -19(X))  (byte). 

rOH  MONTH  —  current  month  (Q-12)  (byte). 

rlL  DAY  —  day  of  month  (1-28, 29,  30, 3 1)  (byte). 

rlH  HOUR  —  hour  (0-23)  (byte). 

r2L  MINUTE  —  minute  (0-59)  (byte). 

r2H  SECOND  —  seconds  (0-59)  (byte). 

Returns:  nothing. 

Destroys:       assume  a,  x,  y,  r0-rl5. 

Description:  SetTimeDate  is  a  clock  driver  routine  for  setting  a  new  time  and  date.  Most 
clock  drivers  do  no  error  checking  on  the  parameters  and  expect  valid  values 
(passing  a  nonexistent  day  in  a  month  is  a  no-no). 

Note:  To  be  sure  the  time  is  set  correctly,  disable  interrupts  around  the  call  to 

SetTimeDate. 

See  also:        ReadClock,  Clocklnt,  SetAlarm,  ResetAIarm. 
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SetUserPattern 


ISetUserPattern  (AppieT 


graphics] 


Function: 
Parameters: 

returns: 
Alters: 

Destroys: 
Description: 

Example: 
See  also: 


Upload  an  cight-byte  pattern  definition  to  a  GEOS  system  pattern. 

a       GEOS  system  pattern  number  to  alter. 

rO      pointer  to  eight-byte  pattern  definition  (word). 


nothing. 
curPattern 

a,y 


altered  so  that  the  new  pattern  becomes  the  current  pattern. 
rO  is  unchanged. 


SetUserPattern  uploads  an  eight-byte  pattern  definition  to  the  system  pattern 
space  in  auxiliary  high  memory.  This  is  the  only  convenient  way  to  modify  the 
system  pattern  definitions  under  Apple  GEOS. 


GetPattern,  SetPattern. 
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Sleep 


Sleep  (Apple,  C64,  C128) 


process 


Function: 

Parameters: 

Returns: 

Destroys: 

Description: 


Note: 


Pause  execution  of  a  subroutine  ("go  to  sleep")  for  a  given  time  interval. 
rO      DELAY  —  number  of  vblanks  to  sleep  (word), 
nothing:  does  not  return  direcdy  to  caller  (see  description  below). 
a,x,  y 

Sleep  stops  executing  the  current  subroutine,  forcing  an  early  rts  to  the  routine 
one  level  lower,  essentially  putting  the  current  routine  "to  sleep."  At  Interrupt 
Level,  the  DELAY  value  assocated  with  each  sleeping  routine  is  decremented. 
When  the  the  DELAY  value  reaches  zero,  MainLoop-  removes  the  sleeping 
routine  from  the  sleep  table  and  perfomrs  a  jsr  to  the  instruction  following  the 
original  jsr  Sleep,  expecting  a  subsequent  rts  to  return  control  back  to 
MainLoop.  For  example,  in  the  normal  course  of  events,  MainLoop  might  call 
an  icon  event  service  routine  (after  an  icon  is  clicked  on).  This  service  routine  can 
perform  a  jsr  Sleep.  Sleep  will  force  an  early  rts,  which,  in  this  case, 
happens  to  return  control  to  MainLoop.  When  the  routine  awakes  (after  DELAK 
vblanks  have  occurred),  MainLoop  performs  a  jsr  to  the  instruction  that  follows 
tiie  original  jsr  Sleep.  When  this  wake-up  jsr  occurs,  it  occurs  at  some  later 
time  the  contents  of  the  processor  registers  and  GEOS  pseudoregisters  are 
uninitialized.  A  subsequent  rts  will  return  to  MainLoop. 

Sleeping  in  Detail: 

\:  The  application  calls  Sleep  with  a  jsr  Sleep.  The  jsr  places  a  return 
address  on  the  stack  and  transfers  the  processor  to  the  Sleep  routine. 

2:  Sleep  pulls  the  return  address  (top  two  bytes)  from  the  stack  and  places  those 
values  along  with  the  DELAY  parameter  in  an  internal  sleep  table. 

4:  Sleep  exectues  an  rts.  Smce  the  original  caller's  return  address  has  been 
pulleid  from  the  stack  and  saved  in  the  sleep  table,  this  rts  uses  the  next  two 
bytes  on  the  stack,  which  it  assunxs  comprise  a  valid  return  address.  (Note:  it 
is  imperitive  that  tiiis  is  in  fact  a  return  address;  do  not  save  any  values  on  die 
stack  before  calling  Sleep.) 

5:  At  Interrupt  Level  GEOS  decrement  sthe  sleep  timer  until  it  reaches  zero. 

6:  On  every  pass,  MainLoop  checks  the  sleep  timers.  If  one  is  zero,  then  it 
removes  that  sleeping  routine  from  the  table,  adds  one  to  the  return  address  it 
pulled  from  the  stack  (so  it  points  to  the  instruction  following  the 
jsr  Sleep),  and  jsr's  to  this  address.  Because  no  context  information  is 
saved  along  with  the  sleep  address,  the  awaking  routine  cannot  depend  on  any 
values  on  the  stack,  in  the  GEOS  pseudoregisters,  or  in  the  processor's 
registers. 

A  DELAY  value  of  $0(XX)  will  cause  the  routine  to  sleep  only  until  the  next  pass 
through  MainLoop. 


CONflDENTIAL 
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Sleep 


When  debugging  an  application,  be  aware  that  Sleep  alters  the  nonnal  flow  of 
control- 


Example: 

See  also:  InitProcesses* 
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SlowMouse 


SlOWMOUSe    (Apple,  C64,  C128)  input  driver| 

Function:       Kills  any  accumulated  speed  in  a  non-proportional  input  device. 
Parameters:  none. 
Returns:  nothing 

Alters:  internal  input-driver  speed  variables,  if  any. 

Destroys:       assume  a,  x,  y,  rO-rlS 

Description:  Input  drivers  for  non-proportional  input  devices,  such  as  a  joystick,  will  often 
internally  associate  a  speed  and  velocity  with  movement  This  way  the  pointer  can 
speed  up  when  the  user  is  trying  to  move  large  distances.  SlowMouse  will  tell 
the  input  driver  to  kill  any  accumulated  speed,  effectively  stopping  the  pointer  at  a 
specific  location  and  forcing  it  to  regain  momentum.  Depending  on  the  input 
driver,  SlowMouse  may  or  may  not  have  an  effect  on  the  pointer's  movement 
The  standard  mouse  driver,  for  example,  simply  performs  an  rts  but  some  other 
input  driver  may  actually  copy  the  value  in  minMouseSpeed  to  its  own  internal 
speed  variable. 

GEOS  calls  SlowMouse  when  it  drops  menus  down.  A  driver  that  has  velocity 
variables  should  adjust  the  current  speed  so  that  the  pointer  does  not  immediately 
jump  off  Ae  menu.  An  application  may  want  to  call  SlowMouse  when  the  user 
is  required  to  make  precise  movements. 

See  also:       UpdateMouse,  InitMouse,  SetMouse,  KeyFilter. 
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SmailPutChar 


ISmallPutChar  (Apple,  C64,  cns) 


text! 


Function: 
Parameters: 

Uses: 
Returns: 

Destroys: 


Description: 


Note: 


Example: 
See  also: 


Print  a  single  character  without  the  PutChar  overhead 

a        CHAR  —  character  code  (byte). 

r  1 1    XPOS  —  x-coordinate  of  left  of  character  (word). 

rlH    YPOS  —  y-coordinate  of  character  baseline  (word). 

same  as  PutChar. 

rl  1    x-position  for  next  character. 
rlH  unchanged 

CpmmodQT?; 

a,  X,  y,  rlL,  r2-rl0,  rl2,  rl3 

Apple: 

a,  x,  y,  rlL,  r2 

SmailPutChar  is  a  bare  bones  version  of  PutChar.  SmailPutChar  will  not 
handle  escape  codes,  does  no  margin  faulting,  and  does  not  normalize  the  x- 
coordinates  on  GEOS  128. 

SmailPutChar  will  assume  the  character  code  is  a  valid  and  printable  character 
Any  portion  of  the  character  that  lies  above  windowTop  or  below 
windowBottom  will  not  be  drawn.  If  a  character  lies  partially  outside  of 
leftMargin  or  rightMargin,  SmailPutChar  will  only  print  the  portion  of  the 
character  lies  within  the  margins.  SmailPutChar  will  also  accept  small  negative 
values  for  the  character  x-position,  allowing  characters  to  be  clipped  at  the  left 
screen  edge. 

Partial  character  clipping  at  die  left  margin,  including  negative  x-postion  clipping, 
is  not  supported  by  early  versions  of  GEOS  64  (earlier  than  vl.4)  —  the  entire 
character  is  clipped  instead.  Full  left-margin  clipping  is  supported  on  all  other 
versions  of  GEOS:  GEOS  64  vl.4  and  above,  GEOS  128  (both  in  64  and  128 
mode),  and  Apple  GEOS. 

Like  PutChar,  159  is  the  maximum  CHAR  value  tfiat  SmailPutChar  will 
handle  correctiy.  Most  fonts  will  not  have  characters  for  codes  beyond  129. 


PutChar,  PutString. 


r  J 
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SoftSprHandler 


SoftSprHandler  (Apple) 


sprite 


Function:  Software. sprite  handler. 
Parameters:  none. 


Uses: 


Returns: 
Alters: 
Destroys: 
Description: 


Note: 


mobenble 

moby2 

niobx2 

reqlxpos-reqTxpos 
moblypos-mob7ypos 

nothing. 

of  f Fla g  $40     Flag  to  Redraw  mouse  at  next  interrupt, 

a,  X,  y,  r0-rl5 

SoftSprHandler  is  the  routine  MainLoop  calls  to  update  die  software  sprites. 
This  involves  redrawing  them  if  diey  have  been  temporarily  removed  (by  a  call  to 
TempHideMouse,  perhaps)  or  erasing  and  redrawing  them  if  they  have  moved. 
An  application  will  normally  have  no  need  to  call  this  routine  direcdy,  assuming 
MainLoop  is  being  returned  to  normally. 

This  is  where  sprites  are  physically  repositioned.  A  call  to  PosSprite,  for 
example,  only  updates  the  reqXposN  and  mobNYpos  request  position 
variables  associated  with  the  sprite.  The  actual  physical  position  does  not  change 
until  SoftSprHandler  is  called  (usually  at  MainLoop)  to  redraw  the  sprites. 

SoftSprHai\.dIer  draws  higher  numbered  sprites  first  so  that  sprites  with  lower 
numbers  will  appear  on  top  of  sprites  with  higher  numbers.  Sprite  #5,  for 
example,  will  appear  on  top  of  sprite  #4  when  they  are  drawn  together. 

SoftSprHandler  does  not  use  reqXposO  and  mobOypos  because  the  mouse 
sprite  is  redrawn  at  intenrupt  level. 


See  also:       TempHideMouse,  HideOnlyMouse. 
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SortAlpha 


SortAlpha  (Apple) 


utility 


Function:       Casc-inscnsitive  alphanumeric  sort 

Parameters:    rO      LIST  —  pointer  to  unsorted  list  (word). 

rl      NUMRECS  —  number  of  16-byte  records  in  the  list 

Returns:        list  sorted 


Destroys:       a,  x,  y,  rl-r4. 


Description: 


Note: 


SortAlpha  sorts  an  arbitrarily  large  list  of  16-byte  ASCII  records.  The  record 
size  is  currendy  fixed  at  16-bytes  (the  number  of  characters  in  a  GEOS  filename), 
although  future  versions  of  Apple  GEOS  will  probably  make  the  record  size 
variable. 

SortAlpha  uses  a  selection  sort  algorithm,  which  works  well  with  small  records 
and  has  a  running  time  proportional  to  NUMREC^.  SortAlpha  ignores  letter 
case  in  its  comparisons. 

SortAlpha  correctiy  handles  the  trivial  cases  where  NUMRECS  is  either  zero  or 
one. 


Example: 


REC_SI2E  —  16 

LoadW 
LoadW 
jsr 
rts 


/always  16  in  Apple  GEOS  vl.O 

rO^lData  ;point  to  record  list 

rl,#NDM_RECS  /number  of  records  to  sort 

SortAlpha  :qo  sort  them 

;exit 


Data: 

.byte  "ZETA  " 

.byte  -0123456789ABcDeF'« 

.byte  "gAMma  over  beta  ** 

.byte  "stewardesses  " 

.byte  -123ABC123abc 

.byte  "abcdefghi jklmnop" 

.byte  ••qrstuvwxy2012345'' 

.byte  "stewardess  *" 

.byte  "beta 

.byte  "alpha  " 

.byte  "delta  " 

.byte  "steward 

NUM^RECS  -  ((*-Data)/REC_SIZE) 

.if""    (   (Data  +  NUM_RECS*REC_SIZE)    !-  *) 

.echo  Something  is  wrong  with  sort  data 
.endif 
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StartAppI  (Apple,  C64,  C128) 


mid-level  disk! 


Function:  Warmstart  GEOS  and  start  an  application  that  is  already  loaded  into  memory. 
Parameters:    These  are  all  passed  on  to  the  application  being  started. 


rOL 


Tl 


r3 


START.ADDR  —  start  address  of  application  (word). 
OPTIONS : 
bit?:  0  not  passing  a  data  file. 

1  r2  and  r3  contain  pointen  to  disk  and  data  file  names, 
bit  6:  0  not  printing  data  file. 

printing  data  file;  application  should  print  file  and  exit 
DATA^DISK  —  only  valid  if  bit  7  or  bit  6  of  OPTIONS  is  set:  pointer 
to  name  of  the  disk  that  contains  the  data  file,  usually  a  pointer  to  one  of 
the  Dr;cCurDkNm  buffers  (word). 

DATA.FILE  —  only  valid  if  bit  7  or  bit  6  of  OPTION  is  set:  pointer  to 
name  of  the  data  file  (word). 


Returns: 
Passes: 


never  retutrns. 

warmstarts  GEOS  and  passes  the  following  to  the  application  at  START^ADDR: 
rO        as  originally  passed  to  StartAppI. 
r2        as  originally  passed  to  StartAppI  (use  dataDiskName). 
r3        as  originally  passed  to  StartAppl.(use  dataFileName). 
dataDiskName     contains  name  of  data  disk  if  bit  7  of  rO  is  set. 
dataFileName      contains  name  of  data  file  if  bit  6  of  rO  is  set 

Alters :  GEOS  brought  to  a  warmstart  state. 

Destroys:  n/a 


Description: 


Example: 
See  also: 


StartAppI  warmstarts  GEOS  and  jsr's  to  START_ADDR  as  if  the  application 
had  been  loaded  from  the  deskTop.  GetFile  and  LdAppIic  call  StartAppI 
automatically  when  loading  an  application. 

StartAppI  is  useful  for  bringing  an  application  back  to  its  startup  state.  It 
completely  warmstarts  GEOS,  resetting  variables,  intializing  tables,  clearing  the 
processor  stack,  and  executing  the  application's  initialization  code  with  a  jsr  from 
MainLoop. 


LdAppIic,  GetFile,  WarmStart. 
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StartASCII 


StartASCII  (Apple,  C64,  cm) 


printer  driver  I 


Function:       Enable  ASCII  text  mode  printing. 


Parameters: 


Commodore 

rl  WORKBUF  —  pointer  to  a  640-byte  work  buffer  for  use  by  the  printer 
driver.(word).  PrintASCII  uses  this  work  area  as  an  intermediate 
buffer,  the  buffer  must  stay  intact  throughout  the  entire  page. 


Apple 
none. 


Returns: 
Destroys: 


STATUS  —  printer  error  code;  $00  =  no  error. 


Description: 


Commodore 
assume  a,  y,  r0-rl5. 

Applg 

assume  a,  y,  r0-r4. 

StartASCII  enables  ASCII  text  mode  printing.  An  application  calls 
StartASCII  at  the  beginning  of  each  page.  It  assumes  that  InitForPrint  has 
already  been  called  to  initialize  the  printer. 


C64  &  C128:  StartASCII  takes  control  of  the  serial  bus  by  opening  a  fake  Commodore  file 
structure  and  requests  the  printer  (device  4)  to  enter  listen  mode.  It  then  sends  the 
proper  control  sequences  to  place  the  printer  into  text  mode. 


Apple: 


Example: 


StartASCII  sends  the  proper  control  sequences  to  place  the  printer  into  ASCII 
mode.  It  reestablishes  the  proper  text  mode  as  set  by  SetMode,  but  it  does  not 
reset  the  printer.  This  allows  an  application  to  mix  graphics  and  ASCII  text  on  the 
same  page. 


See  also:        PrintASCII,  StopPrint,  StartPrint 
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StartMouseMode 


StartMoUSeMode   (Apple,  C64,  C128)  mouse/sprite| 

Function:       Instructs  GEOS  to  start  or  restart  its  monitoring  of  the  input  device  (usually  a 
mouse  but  depending  on  the  input  driver  may  be  a  joystick  or  other  device). 

MOUSEX  —  x-position  to  start  mouse  at  (word)  If  this  parameter  is 
$(X)00,  then  the  mouse  position  is  not  changed  and  the  mouse  velocity  is 
not  altered 

MOUSEY  —  y-position  to  start  mouse  at  (byte), 
cany  flag:    0  =  same  as  setting  MOUSEX  to  $0(XX). 
1=  no  effect 


Parameters:  rll 


y 

St 


loaded  with  address  of  SystemMouseService. 
loaded  with  address  of  SystemFaultService. 
$00 


MOUSEON^BIT  set  by  MouseUp. 
sprite  #0  bit  set  by  MouseUp. 

Destroys:       a,  x,  y,  r0-rl5 

Description:  StartMouseMode  Instructs  GEOS  to  start  or  restart  its  monitoring  of  the  input 
device.  Most  normal  GEOS  applications  will  not  need  to  call  this  routine  because 
it  is  called  internally  by  both  DoMenu  and  Dolcons.  If  an  application  is  not 
using  icons  nor  menus,  it  should  call  StartMouseMode  during  its  initialization. 

StartMouseMode  does  the  following: 

1:  If  the  carry  flag  is  set  and  the  MOUSEX  parameter  is  non-zero,  then 
MOUSEX  is  copied  into  mouseXPos,  AfOt/5£y  is  copied  into 
mouseYPos,  and  the  input  driver  SlowMouse  routine  is  called.  If  running 
under  GEOS  128,  MOUSEX  is  first  passed  through  NormalizeX  before 
getting  loaded  into  mouseXPos. 


Alters:  mouseVector 

mouseFauItVec 
faultData 
mouseXPos 
mouseYPos 
mouseOn 
mobenble 


2:  The  address  of  the  internal  SystemMouseService  routine  is  loaded  into 
mouseVector  and  the  address  of  the  internal  SystemFaultService  routine 
is  loaded  into  mouseFauItVec. 


3:  A  $00  is  stored  into  faultData,  clearing  any  mouse  faults. 

4:  MouseUp  is  called  to  enable  the  mouse. 

64  &  128:      If  the  mouse  will  be  repositioned,  then  disable  interrupts  around  the  call  to 
StartMouseMode.  It  is  not  necessary  to  disable  intermpts  under  Apple  GEOS. 

Example: 

/Intialize  the  mouse  and  start  it  at  screen  center 
Mouselnit: 

LoadW       rllr#(SC_PIX_WIDTH/2)  ; screen  center 

Idy  * (SC_PIx2hEIGHT/2) 

sec  ;set  to  move  mouse 

.if     (C64   I  I  C128) 
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StartMouseMode 


php 
sei 

jsr  StartMouseMode 
pip 

•else  ; (APPLE) 

jsr  StartMouseMode 
.endif 

rts 


See  also:       ClearMouseMode,  MouseUp,  MouseOff,  SlowMouse,  DoMenu, 
Dolcons,  TempHideMouse,  HideOnlyMouse. 
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StartPrint 


StartPrint  (Apple,  C64,  ci28) 


printer  driver  | 


Function:       Enable  graphics-mode  printing- 


Parameters: 


CbmmcKjQrp 

rl  WORKBUF  —  pointer  to  a  1,920-byte  work  buffer  for  use  by  the 
printer  driver. (word).  PrintBuffer  uses  this  work  area  as  an 
intermediate  buffer,  this  buffer  must  stay  intact  throughout  the  entire 
page. 


Apple 
hone. 


Returns: 
Destroys: 


STATUS  —  printer  error  code;  $00  =  no  error. 


Description: 


assume  a,  y,  r0-rl5. 

Apple 

assume  a,  y,  r0-r4. 

StartPrint  enables  graphic  printing.  An  application  calls  StartPrint  at  the 
beginning  of  each  page.  It  assumes  that  InitForPrint  has  already  been  called  to 
initialize  the  printer. 


C64  &  C128:  StartPrint  takes  control  of  the  serial  bus  by  opening  a  fake  Commodore  file 
structure  and  requests  the  printer  (device  4)  to  enter  listen  mode.  It  then  sends  the 
proper  control  swiuences  to  place  the  printer  into  graphics  nxxle. 


Apple: 


Example: 
See  also: 


StartPrint  sends  the  proper  control  sequences  to  place  the  printer  into  graphics 
mode.  It  reestablishes  the  proper  graphics  mode  as  set  by  SetMode,  but  it  does 
not  reset  the  printer.  This  aUows  an  application  to  mix  ASCII  text  and  graphics  on 
the  same  page. 


StopPrint,  StartASCII. 
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StashRAM 


StashRAM  (C64  vi.3  &  ci28) 


memory 


Function:       Primitive  for  transferring  data  to  an  REU, 

Parameters:    rO      CBMSRC  —  address  in  Conimodore  to  start  reading  (word). 


r  1      REUDST  —  address  in  REU  bank  to  put  data  (word). 
r2      COUNT  —  number  of  bytes  to  stash  (word), 
r3L    REUB  ANK  —  REU  bank  number  to  stash  to  (byte). 

r0-r3  unchanged. 

X       error  code:      $00  (no  error)  or  DEV_NOT_FOUND  if  bank  or  REU 

not  available.  " 
a       REU  status  byte  and'ed  with  $60  ($40  =  successful  stash). 


Destroys:  y 

Description:    StashRAM  moves  a  block  of  data  from  Commodore  memory  into  an  REU 
bank.  This  routine  is  a  "use  at  your  own  risk"  low-level  GEOS  primitive 


StashRAM  uses  the  DoRAMOp  primitive  by  calling  it  with  a  CMD  parameter 
of%10010000. 


See  also:       FetchRAM,  SwapRAM,  VerifyRAM,  DoRAMOp,  MoveBData. 


Note: 


Refer  to  DoRAMOp  for  notes  and  warnings. 


Example: 
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This  page  intentionally  left  blank  to  maintain  right/left  (verso/recto) 
page  ordering.  Final  version  will  correct  this. 


StatusCard 


StatusCard  (Apple) 


card  driver! 


Function: 

Parameters: 

Returns: 

Destroys: 
Description: 

Note: 
Example: 
See  also: 


Get  the  current  input/output  status  of  the  printer  card, 
none. 


X 
St 


a,  y. 


STATUS  —  card  error  code;  $00  =  no  error  (byte) 
sign  flag:  set  if  card  ready  to  accept  output, 
carry  flag:  set  if  card  has  input  ready. 


StatusCard  returns  information  about  the  current  state  of  the  card.  The  input- 
ready  and  ready-for-output  flags  are  only  valid  if  the  card  is  capable  of  returning 
this  type  of  information.  This  capability  can  be  checked  with  a  call  to  InfoCard. 

StatusCard  must  be  called  after  an  OpenCard  and  before  a  CloseCard. 


InfoCard. 
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StopPrint 


IStOpPrint  (Apple,  C64,  C128) 


printer  driver  | 


Function: 
Parameters: 


Returns: 
Destroys: 


Flush  output  buffer  and  formfeed  the  printer  (called  at  the  end  of  each  page). 
Commodore 

rO        TEMPBUF  —  pointer  to  a  640-byte  area  of  memory  that  can  be  set  to 
$00  (word). 

rl        WORKBUF  —  pointer  to  a  1,920-byte  work  buffer  used  by 
PrintBuffer  (word). 


Applg 
rlL 


Apple 

X 


FF.SUPPRESS  —  set  to  TRUE  to  suppress  automatic  formfeed  after 
flushing  the  buffer,  normally  set  to  FALSE. 


STATUS  —  printer  error  code;  $00  =  no  enror. 


Description: 

C64  &  C128: 
Apple: 


Example: 
See  also: 


ComtnwlQrp 

assume  a,  x,  y,  r0-rl5. 

Apple 

assume  a,  y,  r0-r4. 

StopPrint  instructs  the  printer  driver  to  flush  any  internal  buffers  and  end  the 
page. 

StopPrint  ends  both  graphic  and  ASCII  printing. 

Commodore  GEOS  printer  drivers  always  formfeed  when  StopPrint  is  called. 

Apple  GEOS  printer  drivers  can  suppress  the  normal  StopPrint  formfeed, 
thereby  flushing  the  print  buffers  but  allowing  the  application  to  resume  printing 
at  the  cuirent  Une.  This  way  ASCII  text  and  graphics  can  be  mixed  on  a  page  with 
alternating  calls  to  StartASCII.  StopPrint,  and  StartPrint. 


StartPrint.  StartASCII. 
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SwapBOata 


SwapBData  (C128)  memoryl 


Function:  Swaps  two  regions  of  memory  within  either  front  RAM  or  back  RAM  (or 
between  one        and  the  other). 

Parameters:    rO  ADDRl  —  address  of  first  block  in  application  memory  (word). 

r  1  ADDRl  —  address  of  second  block  in  application  memory  (word). 

r2  COUNT — number  of  bytes  to  swap  (word). 

r3L  AlBANK— ADDRl  bank:  0  =  front  RAM;  1  =  back  RAM  (byte). 

r3H  A2BANK — ADD/?2  bank:  0  =  front  RAM;  1  =  back  RAM  (byte). 

Returns:        rO-r3  unchanged. 

Destroys:       a,  x,  y 

Description:  SwapBData  is  a  block  swap  routine  that  allows  data  to  be  swapped  in  either 
front  RAM,  back  RAM,  or  between  front  and  back.  If  the  ADDRl  and  ADDRl 
areas  are  in  the  same  bank  and  overlap,  ADDRl.  must  be  less  than  ADDRl. 

SwapBData  is  especially  useful  for  swapping  data  from  front  RAM  to  back 
RAM  or  from  back  RAM  to  front  RAM. 

SwapBData  uses  the  DoBOp  primitive  by  calling  it  with  a  MODE  parameter  of 
$02. 

Note:  SwapBData  should  only  be  used  to  swap  data  within  the  designated  application 

areas  of  memory. 

Example: 

See  also:       MoveBData,  VerifyBData,  DoBOp. 
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SwapMainAndAux 


ISwapMainAndAux  (Apple) 


memory  I 


Function: 

Parameters: 

Destroys: 
Description: 


Example: 
See  also: 


Swaps  a  block  of  memory  on  a  byte-by-bytc  basis  between  application  main 
memory  and  application  aux  memory. 

r  0      SOURCE  —  address  of  block  to  swap  (word). 
r2      COUNT— number  of  bytes  to  swap  (0~48K). 

a,  y»  rO,  rlL,  r2 

SwapMalnAux  swaps  a  block  of  bytes  that  lie  at  the  same  address  in  both  main 
and  auxiliary  application  memory.  This  is  really  only  useful  in  the  area  between 
$6000  and  $8C<X),  where  application  main  and  application  aux  memory  occupy 
the  same  address  space. 


MoveAuxData,  MoveBData,  SwapBData,  SwapRAM. 
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SwapRAM 


SwapRAM  (C64  vL3  &  cns) 


memoryl 


Function: 
Parameters: 

Returns: 


Destroys: 
Description: 


Note: 
Example: 
See  also: 


Primitive  for  swapping  data  between  Commodore  memory  and  an  REU, 

rO  CBMADDR  —  address  in  Commodore  to  swap  (word), 

rl  REUADDR  —  address  in  REU  to  swap  (word). 

r2  COUNT — number  of  bytes  to  swap  (word). 

r3L  REUS  ANK  —  REU  bank  number  to  fetch  from  (byte). 

r0-r3  unchanged. 

X       em)rcode:     $00  (no  error)  or  DEV^NOT^FOUND  if  REUBANK 

or  REU  not  available.  " 
a       REU  status  byte  and'ed  with  $60  ($40  =  successful  swap). 


SwapRAM  swaps  a  block  of  data  in  an  REU  bank  with  a  block  of  data  in 
Commodore  memory.  This  routine  is  a  "use  at  your  own  risk"  low-level  GEOS 
primitive 

SwapRAM  uses  the  DoRAMOp  primitive  by  calling  it  with  a  CMD  parameter 
of  %  10010010. 

Refer  to  DoRAMOp  for  notes  and  warnings. 


StashRAM,  FetchRAM,  VerifyRAM,  DoRAMOp,  SwapBData. 
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TempHideMouse 


TempHideMouse  (Apple,  ci28) 


mouse/sprite] 


Function:  Temporarily  removes  soft-sprites  and  the  mouse  pointer  from  the  graphics  screen. 
Parameters:  nothing. 


Returns: 
Uses: 

Alters: 


Description: 


128: 
Apple: 


Example: 
See  also: 


nothing. 

graphMode 
offFlag 

noEraseSprites 
offFlag 


(128  only). 
(Apple  only). 
(Apple  only). 

set  to  TRUE  (Apple  only). 


Destroys:       a,  x 


TempHideMouse  temporarily  removes  all  soft-sprites  (mouse  pointer  and 
sprites  2-7)  unless  they  are  already  removed.  This  routine  is  called  by  all  GEOS 
graphics  routines  prior  to  drawing  to  the  graphics  screen  so  that  software  sprites 
don't  interfere  with  the  graphic  operations.  An  application  that  needs  to  do  direct 
screen  access  should  call  tins  routine  prior  to  modifying  screen  memory. 

The  sprites  will  remain  hidden  until  the  next  pass  through  MainLoop. 

In  40-column  mode  (bit  7  of  graphMode  is  zero),  TempHideMouse  exits 
immediately  without  affecting  the  hardware  sprites. 

If  bit  7  of  offFlag  is  set,  offFlag  is  set  to  TRUE  (reaffirming  the  fact  that  the 
sprites  and  mouse  are  marked  as  hidden)  and  exits  without  affecting  any  sprites. 
If  noEraseSprites  is  set  to  TRUE,  sprites  2-7  are  not  erased  from  the  screen. 
This  is  useful  for  keeping  sprites  on  the  screen  (and,  therefore,  avoiding  any 
flicker)  if  the  application  is  confident  that  the  graphic  operation  will  not  be  in  the 
area  of  a  sprite. 


HideOnlyMouse. 
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TestPoint 


TeStPoint  (Apple,  C64,  C128) 


Function:       Test  and  return  the  value  of  a  single  point  (pixel). 

Parameters:    r3      XI  —  x-co6ridnate  of  pixel  (word). 

rllL  Yl  —  y-coordinate  of  pixel  (byte). 

where  (XI, Yl)  is  the  coordinate  of  the  point  to  test. 

Uses:  dispBufferOn 

bit  6  — if  set,  test  pixel  in  foreground  screen, 
bit  7  —  if  set,  test  pixel  in  background  buffer. 

(If  both  bit  6  and  bit  7  are  set,  then  only  the  pixel  in  the  background 
screen  is  tested.). 

Returns:        r3,  rllL  unchanged. 

s  t      carry  flag  set  if  point  set;  cleared  if  point  clear. 

Destroys:       a,  x,  y,  r5-r6 

Description:  TestPoint  will  test  a  pixel  in  either  the  foreground  screen  or  the  background 
buffer  (or  both  simultaneously)  and  return  the  pixel's  status  by  either  setting  or 
clearing  the  carry  (x)  flag  accordingly.  The  jsr  TestPoint  is  usually  followed 
immediately  by  a  bcc  or  bcs  so  that  a  set  or  clear  pixel  may  be  handled 
appropriately. 

128:  Under  GEOS  128,  or'ing  DOUBLE  W  into  the  XI  will  automatically  double 

the  x-position  in  80-column  mode.  0?ing  in  ADDl  W  will  automatically  add  1 
to  a  doubled  x-position.  (Refer  to  "GEOS  128  X-po?ition  and  Bitmap  Doubling" 
in  Chapter.®  gitg)  for  more  information.) 

Example: 

See  also:  DrawPoint. 


graphics 
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ToBasiC  (€64^128) 


utility 


Function:  Removes  GEOS  and  passes  control  to  Commodore  BASIC  with  the  option  of 
loading  a  non-GEOS  program  file  (BASIC  or  assembly-language)  and/or 
executing  a  BASIC  command 


Parameters:  rO 
rS 

r7 


CMDSTRING  —  pointer  to  null-terminated  command  string  to  send  to 
BASIC  interpreter. 

DIR.ENTRY  —  pointer  to  the  directory  entry  of  a  standard  Commodore 
file  (PRG  file  type),  which  itself  can  be  either  a  BASIC  or  ASSEMBLY 
GEOS-type  file.  If  this  parameter  is  $0000,  then  no  file  will  be  loaded. 
LOADADDR  —  if  rS  is  non-zero,  then  this  is  the  file  load  address.  For  a 
BASIC  program,  this  is  typically  $801.  If  rS  is  zero  and  a  tokenized 
BASIC  program  is  akeady  in  memory,  then  this  value  should  point  just 
past  the  last  byte  in  the  program.  If  rS  is  zero  and  no  program  is  in 
memory,  this  value  should  be  $803,  and  the  three  bytes  at  $80O-$802 
should  be  $00. 


Returns:  n/a 
Destroys:  n/a 

Description:  ToBasic  gives  a  GEOS  application  the  ability  to  run  a  standard  Commodore 
assembly-language  or  BASIC  program.  It  removes  GEOS,  switches  in  the 
BASIC  ROM  and  I/O  bank,  loads  an  optional  file,  and  sends  an  optional 
command  to  the  BASIC  interpreter. 

Once  ToBasic  has  executed,  there  is  no  way  to  return  directly  to  the  GEOS 
environment  unless  the  RAM  areas  from  $cOOO  through  $c07f  are  preserved 
(those  bytes  may  be  saved  and  restored  later).  To  return  to  GEOS,  the  called 
program  can  execute  a  jump  to  $cOOO  (BootGEOS). 


A  program  in  the  C64  environment  can  check  to  see  if  it  was  loaded  by  GEOS  by 
checking  the  memory  starting  at  $c006  for  the  ASCII  (not  CBMASCH)  string 
"GEOS  BOOT'.  If  loaded  by  GEOS,  the  program  can  check  bit  5  of  $c012:  if 
this  bit  is  set,  ask  the  user  to  insert  their  GEOS  boot  disk;  if  this  bit  is  clear, 
GEOS  will  reboot  from  the  RAM  expansion  unit  To  actually  return  to  GEOS,  set 
CPU  DATA  to  $37  (KRNL  BAS  10  IN)  and  jump  to  $cOOO 
(BootGEOS).  -        -  - 


Example: 


LoadBASIC: 

Loads  a  Conunodore  BASIC  program  and  starts  it 
running.  Assumes  that  the  program  is  a  standard  BASIC 
file  that  loads  at  $801.  This  example  does  little 
error  checking. 


Pass: 


r5 


pointer  to  BASIC  program's  directory 
entry. 


LoadBASIC: 
LoadW 
LoadW 


rO, IRunCommand 
r7,#$801 


; point  at  command  string 
/assume  standard  address 
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jsr  ToBasic 
brJc 


/expect  to  not  return 
/should  never  get  here 


/Text  command  to  send  to  BASIC  interpeter  so  BASIC 

/program  is  started  up  properly, 

RunCommand: 

.byte        "RUN", NULL 


UnblockProcess 


lUnblockProcess  (Apple,  C64,  cns) 


process! 


Function: 
Parameters: 

Returns: 

Destroys: 

Description: 


Note: 

Example: 
See  also: 


Allow  a  process's  events  to  go  through. 

X       PROXIES S  —  number  of  process  (0  -  n-1,  where  n  is  the  number  of 
processes  in  the  table)  (byte). 

X  unchanged 

UnblockProcess  causes  MainLoop  to  again  recognize  a  process's  runable 
flag  so  that  if  a  process  timer  reaches  zero  (causing  the  process  to  become 
runable)  an  event  will  be  generated 

Because  the  GEOS  Intemipt  Level  continues  to  decrement  the  countdown  timer  as 
long  as  the  process  is  not  frozen,  a  process  may  become  runable  while  it  is 
blocked.  As  long  as  the  process  is  blocked,  however,  MainLoop  will  ignore  the 
runable  flag.  When  the  process  is  subsequently  unblocked,  MainLoop  will 
recognize  a  set  runable  flag  as  a  pending  event  and  call  the  appropriate  service 
routine.  Multiple  pending  events  are  ignored:  if  a  blocked  process's  timer  reaches 
zero  more  than  once,  only  one  event  will  be  generated  when  it  is  unblocked.  To 
prevent  a  pending  event  from  happening,  use  RestartProcess  to  unblock  the 
process. 

If  a  process  is  not  blocked  an  unnecessary  call  to  UnblockProcess  will  have 
no  effect 


BlockProcess,  UnfreezeProcess,  EnableProcess,  RestartProcess. 
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UnfreezeProcess 


UnfreezeProcess  (Apple,  C64,  ci28)  processi 


Function:       Resume  (unfreeze)  a  process's  countdown  timer. 

Parameters:    x       PROCESS  —  number  of  process  (0  -       where  n  is  the  number  of 

processes  in  the  table)  (byte). 

Returns:        x  unchanged 

Destroys:  a 

Description:  UnfreezeProcess  causes  a  frozen  process's  countdown  timer  to  resume 
decrementing.  The  value  of  the  timer  is  unchanged;  it  begins  decrementing  again 
from  the  point  where  it  was  frozen.  If  a  process  is  not  frozen,  a  call  to 
UnfreezeProcess  will  have  no  effect. 

Note:  If  a  process  is  not  frozen,  a  call  to  UnfreezeProcess  will  have  no  effect. 

Example: 

See  also:       FreezeProcess,  BlockProcess. 
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UpdateMouse 


UpdateMouse  (Apple,  C64,  cns) 


input  driver! 


Function:       Update  the  mouse  variables  based  on  any  changes  in  the  state  of  the  input  device. 


Parameters:  Commodore: 
none. 


Appig; 

St      cany  flag:  0 
1 


interrupt  was  caused  by  mouse  card 
interrrupt  was  not  caused  by  mouse  card 


Returns: 
Alters: 


nothing 

mouseXPos 
mouseYPos 
mouseData 

pressFlag 
inputData 


mouse  x-position. 
mouse  y-position. 

state  of  mouse  button:  high  bit  set  if  button  is  released;  clear 
if  pressed 

MOUSE^BIT  and  INPUT^BIT  set  appropriately, 
depends  on  device. 


Destroys:       assume  a,  x,  y,  r0-rl5 

Description:  GEOS  calls  UpdateMouse  at  Interrupt  Level  to  update  the  GEOS  mouse 
variables  with  the  actual  state  of  the  input  device.  An  application  should  never 
need  to  call  UpdateMouse. 

A  typical  input  driver's  UpdateMouse  routine  will  scan  the  device  hardware  and 
update  MouseXPos  and  MouseYPos  with  new  positions  if  the  coordinates 
have  changed  It  will  also  update  mouseData  with  the  current  state  of  the  input 
button  (high-bit  set  if  released;  cleared  if  pressed)  ani  set  MOUSE  BIT  in 
pressFlag  if  the  button  state  has  changed  since  the  last  call  to  UpdatelVlouse. 

The  four  byte  inputData  field,  which  was  originally  for  device-dependent 
information,  has  adopted  the  following  standard  offsets: 


inputData+0 


(byte)  8-position  device  direction  (joystick  direction;  mouse 
drivers  convet  a  moving  mouse  to  an  appropriate  direction): 

2 

3       I  1 
6 


inputData-f  1       (byte)  cuircnt  speed  (Comnaodore  joystick  drivers  only). 

Standard  GEOS  input  drivers  should  set  the  INPIIT_BIT  of  pressFlag  if 
inputData+O  has  changed  since  the  last  time  UpdateMouse  was  called. 
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UpdateMouse 


Because  most  GEOS  applications  leave  in  put  Vector  set  to  its  default  $0000 
value,  setting  this  bit  will  usually  have  no  effect 

Apple:  The  Apple  GEOS  version  of  UpdateMouse  will  treat  mouseYPos  as  a  two- 

byte  value,  propagating  any  underflow  into  the  high-byte  at  mouseYPos+1. 
TTiis  gives  the  subsequent  mouse-fault  check  enough  precision  to  detect  whether 
the  user  moved  the  mouse  off  the  top  or  the  bottom  of  the  screen  (a  negative 
number  =  off  the  top  edge).  The  GEOS  mouse  fault  routine  will  always  clear  this 
high-byte  after  constraining  the  mouse  to  the  screen  edges. 

See  also:       SIowMouse,  InitMouse,  SetMouse,  KeyFilter. 
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UpdateParent 


UpdateParent  (Apple) 


mid-level  disk 


Function:       Update  data  om  current  directory  header. 


Parameters:  a 


UPDATE^FLAGS  —  operations  to  perform  (word). 
DEC  NUM  FILES    —  decrement  file  count 


INC  NUM  FILES 
MOD  DATE 
CREATE  DATE 
DEC  DIR  BLKS 
DEC^DIR^BLKS 


—  increment  file  count 
— update  modification  date. 

—  set  creation. 

— decrement  directory  block  count 
_  — increment  directory  block  count 

multiple  changes  can  be  made  in  one  call  by  bitwise  or'ing  these  constants 
together. 


Uses: 
Returns: 


Alters: 


curDirHead 


should  contain  current  directory  header. 


X 

rlOL 


error  ($00  =  no  error), 
directory  page  actually  used. 


curDirHead 
diskBlkBuf 


contains  newly-changed  current  directory  header, 
contains  newly-changed  parent  directory  header  unless 
current  directory  is  volume  directory  (in  which  case  there  is 
no  parent  header). 


Destroys:       a,  y,  rl,  r4,  r5. 


Description: 


UpdateParent  upates  the  current  and  parent  directory  headers  according  to  the 
flags  passed  in  UPDATEJPLAGS.  Whenever  a  the  contents  of  a  subdirectory  are 
altered — whether  adding  or  deleteing  files  or  other  subdirectores  —  the  current 
and  parent  directory  headers  need  to  be  updated  to  reflect  their  new  contents.  The 
high-level  GEOS  routines  will  automatically  call  UpdateParent  when  they  alter 
the  contents  of  a  subdirectory. 

C64  &  C128:  Commodore  GEOS  does  not  support  a  hierarchical  file  system. 


Example: 
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UpdateRecordFIle 


UpdateRecordFile  (Apple,  C64,  cm) 


VLIR  disk 


Function:  Update  the  disk  copy  of  the  VLIR  index  table,  BAM  or  VBM,  and  otfier  VLIR 
information  such  as  the  file's  time/date-stamp.  This  update  only  takes  place  if  the 
file  has  changed  since  opened  or  last  updated. 


Parameters:  none. 


Uses: 


Returns: 
Alters: 


curDrive 
fileWrittent 

fileHeader 
fileSize 

dirEntryBuf 


if  FALSE,  no  updating  occurs  because  file  has  not  been 
written  to. 

VLIR  index  table  stored  in  this  buffer, 
total  number  of  disk  blocks  used  in  file  (includes  index 
block,  GEOS  file  header,  and  all  records), 
directory  entry  of  VLIR  file. 


year,  month,  day,  hours,  minutes      for  date-stamping  file. 


Cpmmodorp; 

curType 

curDirHead 

dir2Headt 

dir3Headt 

Applg; 
fileBytes 

curVBlkno* 

VBMchanged^ 

numVBMBlkst 


GEOS  64  vl.3  and  later,  for  detecting  REU  shadowing, 
this  buffer  must  contain  the  current  d^tory  header. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


total  number  of  bytes  in  file  (written  to  bytes  254, 255, 511, 
and  5 1 2  of  the  master  index  block), 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
X         error  ($00  =  no  error). 

fileWrittent        set  to  FALSE  to  indicate  that  file  hasn't  been  altered  since 
last  updated. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
Destroys:       a,  y,  rl,  r4,  r5. 


Description: 


UpdateRecordFile  checks  the  fileWritten  flag.  If  die  flag  is  TRUE,  which 
indicates  the  file  has  been  altered  since  it  was  last  updated,  UpdateRecordFile 
writes  the  various  tables  kept  in  memory  out  to  disk  (e.g.,  index  table, 
B  AMA^BM)  and  time/date-stamps  the  directory  entry.  If  the  fileWritten  flag  is 
FALSE,  it  docs  nothing. 

UpdateRecord  writes  out  the  index  block,  adds  the  time/date-stamp  and 
(ileSize  information  to  the  directory  entry,  and  writes  out  the  new  BAM/VBM 
witfi  a  call  to  PutDirHead  or  PutVBM  (Commodore  GEOS  and  Apple  GEOS, 
respectively). 
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C64  &  C128:  Because  Commodore  GEOS  stores  the  BAM  in  global  memory,  the  application 
must  be  careful  not  to  corrupt  it  before  the  VLIR  file  is  updated.  If  the 
fileWritten  flag  is  TRUE  and  the  BAM  is  reread  from  disk,  the  old  copy  (on 
disk)  will  overwrite  the  current  copy  in  memory.  In  the  normal  use  of  VLIR  disk 
routines,  where  a  file  is  opened,  altered,  then  closed  before  any  other  disk 
routines  are  executued,  ho  conflicts  will  arise. 


Example: 

See  also:       CloseRecordFile,  OpenRecordFile. 


UpDirectory 


UpDirectory  (Apple) 


high-level  diskl 


Function: 

Parameters: 

Uses: 

Returns: 
Alters: 


Makes  the  parent  directory  the  current  directory, 
none. 


curDrive 
curKBIkno 


current  directory. 


X         error  ($00  =  no  error). 

y         pathname  status  ($00  =  OK;  BFR^OVERFLOW  =  pathname  longer 
than  pathnameBuO- 


curKBIkno 

curDirHead 

pathnameBur 

curDirTabLo^ 

curDirTabHit 


new  current  directory, 
header  of  new  directory. 

system  pathname  buffer  updated  to  reflect  new  path. 


Destroys: 


^used  internally  by  GEOS  disk  routines:  applications  generally  don't  use. 
a,  rOL,  rl,  r2,  r4. 


Description:  UpDirectory  moves  up  one  level  in  the  hierarchical  file  system,  making  the 
parent  directory  the  current  working  directory.  If  UpDirectory  is  called  when 
the  root  directory  is  active,  an  AT_ROOT_DER  error  is  returned. 

UpDirectory  first  changes  the  current  key  block  number,  then  updates  the 
pathname  in  pathnameBuf  calling  GetPathname  if  necessary.  The  current 
directory  header  is  read  in  with  a  call  to  GetDirHead 

C64  &  C128:  Commodore  GEOS  does  not  support  a  hierarchical  file  system. 

Example: 

See  also:     SetGDirEntry,  DeleteDir. 
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lUseSystemFont  (Apple,  C64,  ci28)  text| 

Function:       Begin  using  default  system  font  (BSW  9) 
Parameters:  none. 
Returns:  nothing. 

Alters:  curHeight  height  of  font 

baselineOffset  number  of  pixels  fix>m  top  of  font  to  baseline. 

cardDataPntr  pointer  to  current  font  image  data, 

cu  r In dexTa ble  pointer  to  current  font  index  table. 

curSetWidth  pixel  width  of  font  bitstream  in  bytes. 

Destroys:       a»  x,  y,  rO. 

Description:   UseSystemFont  calls  LoadCharSet  with  the  address  of  the  always-resident 
BSW  9  font.  . 

128 :  In  80-column  mode  a  double-width  BSW  9  font  is  substituted. 

Example: 

See  also:       LoadCharSet,  LoadAuxSet. 


o 
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VerifyBData  (Ci28) 


Function:       Compares  (verifies)  two  regions  of  memory  against  each  other.  The  regions  may 
either  be  in  firont  RAM  or  back  RAM  (or  one  in  front  and  the  other  in  back). 

Parameters:    rO  ADDRl  —  address  of  first  block  in  application  memory  (word). 

rl  ADDR2  —  address  of  second  block  in  application  memory  (word). 

r2  COUNT — number  of  bytes  to  compare/verify  (word). 

r3L  AlBANK— ADD/?7  bank:  0  =  front  RAM;  1  =  back  RAM  (byte). 

r3H  A2B  ANK — ADDRl  bank:  0  =  front  RAM;  1  =  back  RAM  (byte). 

Returns:        r0-r3  unchanged. 

X       $00  if  data  matches;  $ff  if  mismatch. 


Destroys:       a,  y 

Description:  VerifyBData  is  a  blpck  verify  routine  that  allows  the  data  in  one  region  of 
memory  to  be  compared  to  the  data  in  another  region  in  memory.  The  regions 
may  be  in  either  front  RAM,  back  RAM,  or  in  front  and  back.  The  ADDRl  and 
ADDRl  areas  may  overlap  even  if  they  are  in  the  same  bank. 

VerifyBData  uses  the  DoBOp  primitive  by  calling  it  with  a  MODE  parameter 
of  $03. 

Note:  VerifyBData  should  only  be  used  to  compare  data  within  the  designated 

application  areas  of  memory. 

Example: 

Ss^^  also:        MoveBData,  SwapBData,  DoBOp. 
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VerifyRAM  (C64  vu  &  cns)  mtl^ 


Function:  Primitive  for  verifying  (comparing)  data  in  Commodore  memory  with  data  in  an 
REU. 

Parameters:    rO      CBMADDR — address  in  Commodore  to  start  (word)- 
rl      REUADDR — address  in  REU  bank  to  start  (word). 
r2      COUNT  —  number  of  bytes  to  verify/compare  (word). 
r3L    REUS  ANK — REU  bank  number  to  compare  with  (byte). 

Returns:        r0-r3  unchanged. 

X       error  code:     $00  (no  error)  or  DEV_NOT_FOUND  if  bank  or  REU 

not  available.  " 
a       REU  status  byte  and*ed  with  $60:  $40     data  match 

$20     data  mismatch 

Destroys:  y 

Description:  VerifyRAM  compares  a  block  of  data  in  Commodore  memory  with  a  block  of 
data  in  an  REU  bank.  This  routine  is  a  "use  at  your  own  risk"  low-level  GEOS 
primitive 

VerifyRAM  uses  the  DoRAMOp  primitive  by  calling  it  with  a  CMD  parameter 
of  %10010011. 

Note:  Refer  to  DoRAMOp  for  notes  and  warnings. 

Example: 

See  also:       StashRAM,  FetchRAM,  SwapRAM,  DoRAMOp,  VerifyBData. 


303 


VerticaiLine 


VerticalLine  (Apple,  C64,  cns) 


graphics 


Function: 
Parameters: 


Draw  a  vertical  line  with  a  repeating  bit-pattern. 

a  eight-bit  repeating  pattern  to  use  (not  a  GEOS  pattern  number). 

r4  XI  —  x-coordinate  of  line  (word), 

r3L  Yl  —  y-coordinate  of  topmost  endpoint  (byte). 

r3  H  Y2  —  y-coordinate  of  bottomost  endpoint  (byte). 

where  (X1,Y1)  and  (XI, Y2)  define  the  endpoints  of  the  vertical  line. 

dispBufferOn: 

bit  7  —  write  to  foreground  screen  if  set. 
bit  6  —  write  to  background  screen  if  set 

r3L,  r3H,  r4  unchanged. 

Commodore: 
a,  X,  y,  r5L-r8L 

Apple; 
a,  X,  y 

Description:  VerticalLine  sets  and  clears  pixels  on  a  single  vertical  line  according  to  the 
eight-bit  repeating  pattern.  Wherever  a  1-bit  occurs  in  the  pattern  byte,  a  pixel  is 
set,  and  wherever  a  0-bit  occurs,  a  pixel  is  cleared. 

Bits  in  the  pattern  byte  are  used  top-to-bottom,  where  bit  7  is  at  the  top.A  bit 
pattern  of  %  1 1 1 10000  would  create  a  vertical  line  like: 


Uses: 

Returns: 
Destroys: 


I 


i 


The  pattern  byte  is  always  drawn  as  if  aligned  to  a  card  boundary.  If  the 
endpoints  of  a  line  do  not  coincide  with  card  boundaries,  then  bits  are  masked  off 
the  appropriate  ends.  The  effect  of  this  is  that  a  pattern  is  always  aligned  to 
specific  pixels,  regardless  of  the  endpoints,  and  that  adjacent  lines  drawn  in  the 
same  pattern  align. 

Note:  To  draw  patterned  vertical  lines  using  the  8x8  GEOS  patterns,  draw  rectangles  of 

one-pixel  width  by  calling  the  GEOS  Rectangle  routine  with  identical  x- 
coordinates. 
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VerWriteBIock  (C64,  C128)   very  low-level  disk  I 


Function:       Very  low-level  verify  block  on  disk. 

Parameters:    rlL    TRACK  —  valid  track  number  (byte). 

rlH    SECTOR  —  valid  sector  on  track  (byte). 

r4      BUFFER  —  address  of  buffer  of  BLOCKSIZE  bytes  that  contains  data 
that  should  be  on  this  sector  (word). 

Uses:  curDrive  currently  active  disk  drive. 

curType  GEOS  64  v  1.3  and  later  for  detecting  REU  shadowing. 

Returns:        x       error  ($00  =  no  error). 

Destroys:       a»  y. 

Description:  VerWriteBIock  verifies  the  validity  of  a  recently  written  block.  If  the  block 
does  not  verify,  the  block  is  rewritten  by  calling  WriteBlock.  VerWriteBIock 
is  a  low-level  disk  routine  and  expects  the  application  to  have  already  called 
EnterTurbo  and  InitForlO. 


VerWriteBIock  can  be  used  to  accelerate  die  verifies  that  accompany  multiple- 
sector  writes  by  first  writing  all  the  sectors  and  then  verifying  tiiem.  This  is  often 
faster  than  verifying  a  sector  immediately  after  writing  it  b5:ause  when  writing 
sequential  sectors,  the  GEOS  turbo  code  will  catch  the  sector  interleave.  If  a 
sector  is  written  and  then  immediately  verified,  the  turbo  code  will  need  to  wait 
for  the  disk  to  make  one  complete  revolution  before  die  newly- written  sector  will 
again  pass  under  the  read/write  head.  By  writing  all  the  sectors  first  and  catching 
the  interleave,  then  verifying  all  the  sectors  (again,  catching  die  interleave),  the 
dead  time  when  the  turbo  code  i:>  Waiting  for  the  disk  to  spin  around  is 
minimized.  Many  of  the  higher-level  disk  routines  that  write  multiple  blocks  do 
just  this. 

VerWriteBIock  is  useful  for  multiple-sector  disk  operations  where  speed  is  an 
issue  and  the  standard  GEOS  routines  don't  offer  a  decent  solution. 
VerWriteBIock  can  function  as  the  foundation  of  specialized,  high-speed  disk 
routines. 


Note:  VerWriteBIock  docs  not  always  do  a  byte-by-byte  compare  with  the  data  in 

BUFFER.  Some  devices,  such  as  the  Commodore  1541,  can  do  a  cyclic 
redundancy  check  on  the  data  in  the  block,  and  this  intemal  checksum  is  sufficient 
evidence  of  a  good  write.  Other  devices,  such  as  RAM-expansion  units,  have 
built-in  bytc-by-byte  verifies. 

Apple:  VerWriteBIock  docs  not  exist  in  Apple  GEOS.  To  verify  a  block,  read  it  into  a 

general  purpose  buffer  (diskBlkBuf,  for  example).  If  the  block  reads  without 
an  error,  it  verified.  The  ProDos  device  driver  does  its  own  checksum  on  data 
blocks,  so  a  bytc-by-byte  comparison  of  the  data  isn't  necessary  to  determine  if 
the  block  was  properly  written  —  rereading  the  block  without  an  error  is 
sufficient  evidence  of  a  good  write.  See  PutBIock  for  more  information. 


Example:       Sec  WriteBlock. 


VerWriteBlock 


See  also:       WriteBlock,  PutBIock. 
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WarmStart  (Apple)    Internal 


Function:  Executes  portions  of  the  GEOS  warmstart  procedure  (the  same  warmstart 
executed  before  a  new  application,  desk  accessory,  or  dialog  box  is  started  up). 

Parameters:  none 

Returns:        GEOS  variables  in  a  warmstart  state;  stack  and  application  space  unaffected 
Destroys:       a,  x,  y,  r0-r2 

Description:  WarmStart  is  part  of  the  GEOS  warmstart  procedure.  It  resets  some  GEOS 
variables  and  data  structures  (both  global  and  local)  to  their  default  state,  the  state 
they  are  in  when  an  application,  desk  accessory,  or  dialog  box  is  started  up. 
GEOS  calls  WarmStart  internally,  and  is  of  Uttie  use  to  an  application.  An 
application  that  needs  to  place  GEOS  in  a  warmstart  state  (for  restarting,  for 
example),  is  better  off  using  StartAppI. 

See  also:        Firstlnit,  StartAppI. 
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WriteBlock  (C64,  ci28) 


very  low«level  disk] 


Function: 
Parameters: 

Uses: 

Returns: 

Destroys: 

Description: 


Apple: 


Example: 


Very  low-level  write  block  to  disk. 

rlL    TRACK  —  valid  track  number  (byte). 
rlH    SECTOR — valid  sector  on  track  (byte). 

r4      BUFFER  —  address  of  buffer  of  BLOCKSIZE  bytes  that  contains  data 
to  write  out  (word). 


curDrive 
curType 


currently  active  disk  drive. 

GEOS  64  vl.3  and  later  for  detecting  REU  shadowing. 


error  ($00  =  no  error). 


a,  y. 


WriteBlock  writes  the  block  at  BUFFER  to  the  specified  TRACK  and 
SECTOR.  If  the  disk  is  shadowed,  WriteBlock  will  also  write  the  data  to  the 
shadow  memory.  WriteBlock  is  pared  down  version  of  PutBlock.  It  expects 
the  application  to  have  already  called  EnterTurbo  and  InitForlO,  and  it  does 
not  vcnfy  the  data  after  writing  it 

WriteBlock  can  be  used  to  accelerate  multiple-sector  writes  and  their 
accompanying  verifies  by  writing  all  the  sectors  first  and  then  verifying  them. 
TTiis  is  often  faster  than  verifying  a  sector  immediately  after  writing  it  because 
when  writing  sequential  sectors,  the  GEOS  turbo  coidc  will  catch  the  sector 
interleave.  If  a  sector  is  written  and  then  immediately  verified,  the  turbo  code  will 
need  to  wait  for  the  disk  to  make  one  complete  revolution  before  the  newly- 
written  sector  will  again  pass  under  the  read/write  head.  By  writing  all  the  sex:tors 
first  and  catching  the  interleave,  then  verifying  all  the  sectors  (again,  catchirg  tfie 
interleave),  the  dead  time  when  the  turbo  code  is  waiting  for  the  disk  to  spin 
around  is  minimized  Many  of  the  higher-level  disk  routines  that  write  multiple 
blocks  do  just  this. 

WriteBlock  is  useful  for  multiple-sector  disk  operations  where  speed  is  an  issue 
and  the  standard  GEOS  routines  don't  offer  a  decent  solution.  WriteBlock  can 
function  as  the  foundation  of  specialized,  high-sp^d  disk  routines. 

Apple  GEOS  has  no  WriteBlock  equivalent  Use  PutBlock  instead.  To  write  a 
block  without  verifying  the  data,  set  numDiskRetries  to  $00  before  calling 
PutBlock.  See  PutBlock  for  more  information. 


;Write  sector  from  diskBlkBuf  to  disk  and  then  verify 
if  necessary. 


Pass: 


track 

sector 

verify 


Returns: 

X 


track  number 
sector  on  track 
verify  data?  (TRUE 


error  code 


YES) 
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MyPutBlock : 


80$: 
99$: 


Loaaw 

MoveB 

r xJ^r  uracK 

i  WJLOlwl\  ilUlllMCX 

noveo 

ifi©ctor  number 

jsr 

;ao  Into  turbo  tnocie 

txa 

;set  status  flags 

bne 

99$ 

/branch  if  error  found 

jsr 

InitFbrlO 

/prepare  for  serial  I/O 

jsr 

WriteBlock 

/primitive  write  block 

tixa 

/set  status  flags 

bne 

80$ 

/branch  if  error  found 

Ida 

verify 

/check  verify  flag 

beq 

80$ 

/branch  if  not  verifying 

jsr 

VerWriteBlock 

/verify  block  we  wrote 

jsr 

DoneWithIO 

/restore  after  I/O  done 

rts 

/exit 

See  also:       PutBIock,  ReadBlock,  VerWriteBlock. 
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WriteFile  (Apple,  C64,  cns) 


mid-level  disk 


Function:       Write  data  to  a  chained  list  of  disk  blocks. 
Parameters:    r7        DATA  —  pointer  to  start  of  data  (word). 
Commodore: 

r6  TSTABLE  —  pointer  to  a  track/sector  list  of  blocks  to  wnte  data  to 
(unused  but  allocated  in  the  BAM),  usually  a  pointer  to 
fi!eTrScTab+2;  BlkAUoc  can  be  used  to  build  such  a  list.  Apple 
GEOS  uses  the  table  in  INDEXBLOCKBUF  (word). 


Uses: 


curDrive 

CQiinmcK^prg; 
curType 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing. 


Returns: 
Destroys: 


Appig; 

RWbank  bank  BUFFER  is  in  (MAIN  or  AUX). 

INDEXBLOCKBUF     index  block  for  chain  (in  auxiliary  memory;  see 

below  for  information  on  accessing  this  buffer). 

X         error  ($00  =  no  error). 


Apple; 

a,  y,  rl,  r4. 

Commodorg; 
•  a,  y,  rl-r2,  r4, r6-r7. 

Description:  WriteFile  writes  data  from  memory  to  disk.  The  disk  blocks  are  verified,  and 
any  blocks  that  don't  verify  are  rewritten. 

Although  the  name  "WriteFile"  implies  that  it  writes  "files,"  it  actually  writes  a 
chain  of  blocks  and  doesn't  care  if  this  chain  is  an  entire  sequential  file  or  merely 
a  VLIR  record. 

C64  &  C128:  WriteFile  uses  the  track/sector  table  at  TSTABLE  as  a  list  of  linked  blocks  that 
comprise  the  chain.  The  end  of  the  chain  is  marked  with  a  track/sector  pointer  of 
$00,$ff.  WriteFile  copies  the  next  254  bytes  from  the  data  area  to 
diskBlkBuf+2,  looks  two-bytes  ahead  in  the  TSTABLE  for  the  pointer  to  the 
next  track/sector,  and  copies  those  two-bytes  to  dskBIkBuf+0  and 
dskBlkBuf+1.  WriteFile  then  writes  this  block  to  disk.  This  is  repeated  until 
the  end  of  the  chain  is  reached 

WriteFile  does  not  flush  the  BAM  (it  does  not  alter  it  eidier  —  it  assumes  the 
blocks  in  the  track/sector  table  have  already  b^n  allocated).  See  BlkAUoc, 
SetNextFree,  and  AlIocateBIock  for  information  on  allocating  blocks.  See 
PutDirHead  for  more  information  on  writing  out  the  BAM. 


Apple: 


Apple  GEOS  uses  the  internal  index  block  buffer  INDEXBLOCKBUF  (in 
aujoliary  memory)  as  a  list  of  blocks  that  comprise  the  chain.  Applications  cannot 


311 


WriteFile 


directly  access  this  buffer,  but  MoveAuxData  can  be  used  to  copy  the  index 
block  from  the  appliciation's  memory  space  to  INDEXBLOCKBUF: 


AOXtoMAIN 
MAINtoAOX 

LoadW 

LoadW 

LoadW 

Ida 

jsr 


%10000000 
—  %01000000 

rO,  ImylndexBlock 
rl,   # INDEXBLOCKBUF 
r2,  «BLOCKSIZ£ 
#MAINtoAOX 
MoveAuxData 


;copy  from  app.  main 
;to  temp  high  aux 
;move  a  full  block 
;copy  main  to  aux 


WriteFile  does  not  write  the  index  block  out  to  disk, 

WriteFile  does  not  flush  the  VBM  cache  (it  does  not  alter  it  either — it  assumes 
the  blocks  in  the  index  block  have  akeady  been  allocated).  See  BlkAlIoc, 
SetNextFree,  and  AlIocateBIock  for  information  on  allocating  blocks.  See 
PutVBM  for  more  information  on  flushing  the  VBM  cache. 

WriteFile  first  writes  the  blocks  out  in  a  tight  loop,  then  makes  a  second  pass, 
rereading  each  into  diskBikBuf  to  verify  the  data.  If  a  verify  error  occurs,  the 
entire  file  is  rewritten. 


Example: 
See  also: 


SaveFile,  WriteRecord,  ReadFile. 


312 


WriteRecord 


WriteRecord  (Apple,  C64,  ci28) 


VLIR  disk 


Function: 


Write  data  to  the  cunent  VLER  record. 


Parameters:  r2 


Uses: 


Returns: 
Alters: 


r7 


BYTES  —  data  bytes  to  write  to  record.  Commodore  version  can  write 
up  to  32,258  bytes  (127  Commodore  blocks);  Apple  version  can  write 
up  to  64,512  (126  ProDOS  blocks)  (word). 
RECD  ATA  —  pointer  to  start  of  record  data  (word). 


curDrive 
nieWrittent 

curRecord 
fileHeader 

Cpmmcxlprp; 

curType 

curDirHead 

dir2Headt 

dirSHeadt 

Apple: 

RWbank 

curVBikno+ 

VBMchangedt 

numVBMBIkst 


if  FALSE,  assumes  record  just  opened  (or  updated)  and 

reads  BAMATBM  into  memory. 

current  record  pointer. 

VLIR  index  table  stored  in  this  buffer. 


GEOS  64  vl.3  and  later  for  detecting  REU  shadowing, 
current  directory  header/B  AM. 
(BAM  for  1571  and  1581  drives  only) 
(BAM  for  1581  drive  only) 


bank  RECD  ATA  is  written  from  (MAIN  or  AUX). 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines, 
used  by  VBM  cacheing  routines. 


^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
X         error  ($00  =  no  error). 


fileWrittent 

fileHeader 

fileSize 

Commodore: 
fileTrScTab 


curDirHead 

dir2Headt 

dirSHeadt 

Applg; 
fileBytes 


set  to  TRUE  to  indicate  the  file  has  been  altered  since  last 
updated 

index  table  adjusted  to  point  to  new  chain  of  blocks  for 
current  record. 

adjusted  to  reflect  new  size  of  file. 


Contains  track/sector  table  for  record  as  returned  from 

B  Ik  Alloc.  The  track  and  sector  of  the  first  block  in  the 

record  is  at  fileTrScTab+0  and  fileTrScTab+l.  The  end 

of  the  table  is  marked  with  a  track  value  of  $00. 

current  directory  header/B  AM  modified  by  write  operation. 

(BAM  for  1571  and  1581  drives  only) 

(BAMfor  1581  drive  only) 


adjusted  to  reflect  new  size  of  file. 
^used  internally  by  GEOS  disk  routines;  applications  generally  don't  use. 
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WriteRecord 


Destroys: 


Description: 


Note: 


Apple: 


Apple: 

a,  y,  rl-r4,  r6,  r7,  r8H. 

ComiTiodgre; 
a,  y,  r0-r9. 

WriteRecord  writes  data  to  the  current  record  All  blocks  previously  associated 
with  the  record  are  freed.  BIkAIloc  is  then  used  to  allocate  enough  new  blocks 
to  hold  BYTES  amount  of  data  (Apple  GEOS  will  allocate  one  ProDOS  index 
block  in  addition  to  the  data  blocks).  The  data  is  then  written  to  the  chain  of 
sectors  by  calling  WriteFile.  The  flleSize  variable  is  updated  to  reflect  the  new 
size  of  the  file.  Apple  GEOS  also  updates  fileBytes* 

WriteRecord  does  does  not  write  the  BAMA^BM  and  internal  VLIR  file 
information  to  disk.  Call  CIoseRecordFile  or  UpdateRecordFiie  when  done 
to  update  the  disk  with  this  information. 

WriteRecord  correctly  handles  the  case  where  the  number  of  bytes  to  write 
{BYTES,  R2)  is  zero.  The  record  is  freed  and  marked  as  allocated  but  not  in  use. 

When  WriteRecord  returns,  the  index  block  of  the  record  just  written  is  in  the 
aux.  memory  buffer  INDEXBLOCKBUF.  Applications  cannot  access  this 
buffer  direcdy.  MoveAuxData  can  be  used,  however,  to  copy  the  block  into  the 
appliciation's  memory  space  if  access  to  it  is  necessary: 


AUXtoMAIN 
MAINtoAUX 

LoadW 

LoadW 

LoadW 

Ida 

jsr 


%10000000 
==  %01000000 

rO,   # INDEXBLOCKBUF 
rl,  #diskBlkBuf 
r2,  #BLOCKSIZE 
#APXtoMAIN 
MoveAuxData 


/copy  from  index  blk 
;to  tiemp  buffer 
;move  a  full  block 
;copy  aux  to  main 


Example: 
See  also: 


ReadRecord,  WriteFile. 
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GEOS  Quick  Reference 


Name 

€64 

C128 

Apple 

Description 

AllocateBIock 

$9048 

S9048 

S0300 

Mark  a  disk  block  as  in-use. 

AppendRecord 

$c289 

$c289 

S0330 

Insert  a  new  VLIR  record  after  the  current  record. 

AuxDExil 

n/a 

n/a 

Sefa9 

Aux-driver  deinstall  and  exit  routine. 

AuxDInt 

n/a 

n/a 

Sefa3 

Aux-driver  interrupt  level  routine. 

AuxDKevFilter 

n/a 

n/a 

Sefa6 

Aux-driver  keypress  filter. 

AuxDMain 

n/a 

n/a 

SefaO 

Aux-driver  MainLoop  level  routine. 

BBMult 

$cl60 

Scl60 

Sfecc 

Byte  by  byte  (single-precision)  unsigned  multiply. 

Bell 

n/a 

n/a 

Sff86 

1000  Hz  Bell  sound. 

BitmapClip 

$c2aa 

Sc2aa 

SfeSa 

Display  a  compacted  bitmap,  clipping  to  a  sub-window. 

BiimapUp 

$cl42 

$cl42 

Sfe54 

Display  a  compacted  bitmap  without  clipping. 

BilOlherClip 

$c2c5 

$c2c5 

SfeSd 

BitmapClip  with  data  coming  from  elsewhere  (e.g..  disk) 

BldGDirEntiy 

$clf3 

$clf3 

$036f 

Build  a  GEOS  directory  entry  in  memory. 

BlkAlIoc 

Sclfc 

Sclfc 

S0351 

Allocate  space  on  disk. 

BlockProcess 

SclOc 

SclOc 

$feb4 

Block  process  from  running.  Does  not  freeze  timer. 

BMuIt 

$cl63 

$cl63 

Sfecf 

Byte  by  word  unsigned  multiply. 

BootGEOS 

ScOOO 

ScOOO 

n/a 

Reboot  GEOS.  Requires  only  128  bytes  at  ScOOO. 

CalcBlksFree 

Scldb 

Scldb 

$0324 

Calculate  total  number  of  free  disk  blocks. 

CallRouline 

$cld8 

Scld8 

$ff08 

pseudo-subroutine  call.  $0000  aborts  call. 

CancelPrinl 

n/a 

n/a 

$6018 

Cancel  printing,  clearing  printer  and  I/O  card  buffers. 

ChangeDiskDevice 

$c2bc 

Sc2bc 

n/a 

Instruct  CBM  drive  to  change  its  serial  device  address. 

ChkDkGEOS 

Sclde 

Sclde 

n/a 

Check  CBM  disk  for  GEOS  format. 

ClearCard 

n/a 

n/a 

$6715 

Clear  any  buffered  I/O  operations. 

ClearMouseMode 

Scl9c 

Scl9c 

$fe9f 

Slop  input  device  monitoring. 

ClearRam 

$cl78 

$cl78 

$fefc 

Clear  memory  to  $00. 

Clocklni 

n/a 

n/a 

$0803 

Clock  driver  interrupt  level  routine. 

CloseCard 

n/a 

n/a 

$670c 

Close  access  to  I/O  card. 

CloseRecordFile 

$c277 

$c277 

$0333 

Qosc  currently  open  VLIR  file. 

CmpFString 

$c26e 

$c26e 

$fefO 

Compare  two  fixed-length  strings. 

CmpString 

$c26b 

Sc26b 

$feed 

Compare  two  null-terminated  strings. 

CopyFString 

$c268 

Sc268 

Sfeea 

Copy  a  fixed-length  string. 

Copy  Full  Screen 

n/a 

n/a 

$ff92 

Fast  vertical  screen  copy. 

CopyLinc 

n/a 

n/a 

SffSf 

Bit-boundary  horizontal  line  copy. 

CopyScreenBlock 

n/a 

n/a 

$ff5c 

Bit-boundary  rectangle  copy. 

Copy  String 

$c256 

Sc256 

$fee7 

Copy  a  null-terminated  string. 

CRC 

$c20e 

Sc20e 

$ffl4 

Cyclic  Reduncancy  Check  calculation. 

Dabs 

$cl6f 

$cl6f 

$fedb 

Double -precision  signed  absolute  value. 

Ddec 

$cl75 

$cl75 

$feel 

Double-prccison  unsigned  decrement. 

Ddiv 

$cl69 

$cl69 

$fed5 

Double-precision  unsigned  division. 

DeleteDir 

n/a 

n/a 

$037c 

Delete  directory. 

DeleteFile 

$c238 

$c238 

$0357 

Delete  file. 

DeleteRecord 

$c283 

Sc283 

$0336 

Delete  current  VLIR  record. 

DisablSprile 

$cld5 

Scld5 

$feab 

Disable  sprite. 

DivideBySeven 

n/a 

n/a 

$ff68 

Quick  division  by  seven  for  direct  screen  access. 

DMull 

$cl66 

$cl66 

$fed2 

Double-precision  unsigned  multiply. 

Dnegate 

$cl72 

Scl72 

Sfede 

Double-precision  signed  negation. 

DoBOp 

n/a 

$c2ec 

n/a 

C128-backram  memory  primitive. 

DoDlgBox 

$c256 

Sc256 

Sffl7 

Display  and  begin  interaction  with  dialog  box. 

Dolcons 

$cl5a 

Scl5a 

$feOc 

display  and  begin  interaction  with  icons. 

DoInlineRetum 

Sc2a4 

Sc2a4 

$fe09 

Return  from  inline  subroutine. 

DoMenu 

$cl51 

SclSl 

$feOf 

Display  and  begin  interaction  with  menus. 

DoneWithIO 

$c25f 

Sc25f 

n/a 

Restore  system  after  I/O  across  CBM  serial  bus. 

DoPreviousMenu 

$cl90 

$cl90 

$fel5 

Retract  sub-menu  and  reactivate  menus  up  one  level. 

DoRAMOp 

$c2d4 

Sc2d4 

n/a 

CBM  RAM-expansion  unit  access  primitive. 

DownDirectory 

n/a 

n/a 

$0381 

Open  subdirectory. 

DrawLine 

$cl30 

Scl30 

$fe33 

Draw,  clear,  or  recover  line  between  two  endpoints. 

DrawPoint 

$cl33 

Scl33 

$fe21 

Draw,  clear,  or  recover  a  sinf^le  screen  point. 

DrawSprite 

Sclc6 

Sclc6 

$fea2 

Define  sprite  image. 
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Name   C64      C128    Apple  Description 


Uouiv 

sir  1 

LAJUDiC'prcvlslUlX  algllCvX  UlViSIUIl* 

rVMihlA.nrACicinn  l^ft  chift  /7Ame  chiftA/1  ^n^ 
Li/\^UUlcpi wwiaiv/ix  icil  911111  ^^ClUa  911111CU  Ul^« 

0 1111  llxl  {^UL 

$c262 

$c262 

Sfec9 

Oouble-Drecision  richt  shift  (7&t(^^  shifted  in^ 

(KTWUk'tW   1^1  W^iA  IV/tl    I                  Jlll&fc                           dlUlbWU  lily* 

$cl09 

$cl09 

$fec3 

Make  a  process  ninable  immediately. 

Ciiauiopn  W 

Scld2 

$cld2 

t91  vOO 

Fnable  snrite 

cnicr  L</CdJv,i  \jy 

Sc22c 

$c22c 

Sff59 

l^ave  annlication  and  return  to  GPOS  rfe^VTmi 

cnici  1  uruo 

Sc9l4 

n'/fl 
11/  tt 

Artivflt^  r^RM  Hiclf  tiirtv^  nn  nirrAnt  HriVA 

/^wlXvttVC  ^X^ITI   V41dl^  lUX  U\/  Ull  VUXIwlll  UXi*v* 

n/a 

n/a 

$ff3e 

Frase  text  character  from  screen 

CaH  1  lUUU 

$c232 

$c232 

n/a 

Deactivate  CBM  dislc  turbo  on  current  drive 

$c244 

Sc244 

n/a 

Ouiclc  file  delete  ^renuires  full  track/sector  Hst^ 

I7Tvrr%A  e  Tn  D 1  r 

1  ur  1  ypcsini«/ix 

11/  a 

n/a 
11/  a 

S0363 

FinH  fllAC  in  rfirActorv  nthAr  fhsin  nirrAnf  rfir<»/*torv 

rUlU   X11C9   Xil  UtiCWlWljr    VJUICl    UIOJI  WUllClll  vlllCvlvljT* 

CptrViR  AM 

Sc2cb 

Sc2cb 

n/a 

Transfer  data  from  CRM  R AM-exnansion  unit 

$cl7b 

$cl7b 

$feff 

Fill  memorv  with  a  tiarticular  bvte 

r  inoD  Mjvi  o  1 1 

Sc2ad 

n/a 

Get  allocation  statue  of  narticular  CRM  disk  block 
vjwv  oitv^ttuvit  dMiiua  %jl  pcuuwuittx  y^oiyk  ui9iw  l/jv/wil* 

rinanie 

SclOb 

SclOb 

S0369 

^Anrrh  for  a  nnrtinilaT*  filA 

rinur  i  ypes 

S0366 

FinH  all  files  of  a  nartimlar  GFO^  tvTV* 
1  liiu  cux  xuca  vix  a  }j<uuvui<u  vJbvyo  ijr^^* 

Firiii  V  dviJDii 

11/  a 

n/a 

$03  6c 

Get  allocation  status  of  narticular  ProDOS  disk  block 

nrsiinii 

$c271 

$c271 

$ffll 

GFOS  startUD  entrv  ooint 

rnariiinjL/ir 

n  /a 

11/  A 

n  /fl 
11/  a 

S036c 

Finrf  a  file  in  a  directorv  other  than  current  rfirectorv 

roiiuw\^naiTi 

$c905 

n/a 

Follow  chain  of  f^R^4  sectors   hiiilHina  traclf /sector  table 

rraiTic  ivcciajigic 

«9ir  1^1 

TV*aw  a  rActanaular  frame  ^011flinA^ 
§1^1  aw  a  icvuuif^uiax  xiOJiic  yuuiiiiicy* 

$039fl 

«9w  J  ^tt 

Mflrlr  a  Hislr  hloclr  as  not.in.iicA 
ivinxiw  tf  uisjw  uiiyviw  sd  iivi*iJi"U9C» 

rreeuir 

n/fl 

n/a 

n/a 

^uJ  ua 

Ptaa  all  hlnoVc  accf%/*i9tAH  u/itK  o  eiiYv4irA/^f/^T\/ 
nCC  all  UlUvKa  odbUCIalCU  Wiui  a  suuuirvduiy. 

FrecFile 

«9  vJ  J  tt 

FrAA  all  hlocire  accocatiatAH  ti/ith  a  filA 
1  ICC  OJX  Ulv/Ui^a  ttddU^aiialcu  wiui  tt  XllC* 

FrcczcProcess 

1  1  ^ 

SIfAhfl 

PaiiCA  a  nrfYCACC  cmmtHi^u/n  ftmA^ 
1  ausc  tt  piuwcaa  vuumuuwii  uinci* 

vj  c  1 1  s  1 1^  I  r  cn  uy 

S039c 

Ga?  first  HirAcforv  Antrv 

VJCi  XlXdi  UlXCvlUljr  ClllXjr* 

S0300 

RabH  sinolA  Hislr  hloclr  info  mAmorv 
xxcau  dxiigic  vxiaiw  uiuviw  xiiiu  iiiciiiuiy* 

«91CO  / 

GnlciilatA  wiHth  of  characfAT  vi/ithoiif  ct\/lA  attrihiitAC 
Vvttiii^uiaic  wiuui  ux  wiittittwici  wiuiuuL  aijic  aiuiuuicSt 

At  III       An  c  t  An  c 

d>  #  7V/V 

n  /fl 
11/  tt 

GAt  GT)M  nrintAr  nnoe  HimAnsione 
wci  \^ovn  piiiiicx  pa^c  uiiiiciuiuua* 

/^Atr\trUA4<4 
vjciL/irneau 

S0379 

RAttH  HirActorv  hAaHAT  into  mATTmr\/ 
ixcau  uiicviuxjr  iicttvici  xiiiu  luciiiury* 

O  At  P14  rfrTn  f r> 

$c92Q 

S0390 

«9  V  J  7  W 

RAaH  a  GFO^  file  hearlAr  into  mAmnrv 
xvcttu  tt  vjbvyo  xxic  iicaucx  xiiiw  iiiciiiuiy« 

vjcinie 

S030f 

Load  GEOS  file 

nAtFrAAnirRIk 

VJCltiCCLi/lI  OlIW 

$clf6 

$clf6 

$0375 

Find  an  emotv  directorv  slot 

1  iiiu  cut  ^tn\jvy   uiiv>wv\jijr   ^tw^*  ^ 

VJCULAA  T  <U  9 

n/a 

n/a 

$ff44 

Transfer  internal  Ld  variables  to  GEOS  nseudorecisters 

n/a 

n/a 

$6012 

Return  current  orintcr  resolution  anH  setahle  attributes 

GetNextChar 

Sc2a7 

Sc2a7 

$fe75 

Get  next  character  from  character  aueue 

OptMY  tnirFntrv 

$9033 

$9033 

$039c 

Get  directorv  entrv  other  than  first 

GAtPatViTiAmA 

n/a 

n/a 

$0384 

Return  current  oath  strini? 

r«AtPflttf>m 

VJvll  Alien t 

n/a 

n/a 

$ff7d 

Get  eieht-bvte  GEOS  nattem  definition 

$c298 

$c298 

$ff56 

Return  nointer  to  current  disk  name 

vjcilx  aJiQOTTl 

SIrl  87 

Sfee4 

«91CC*T 

f^alcitlatA  nAU/  ranHom  numt^r 
\^aiwuiaic  new  xaJiuuiii  iiuiiiia?i* 

«9U  i  U  1 

$clbl 

$fe84 

Calculate  actual  character  si7e  with  attributes 

«9V  X  .^V 

$fe66 

CalciilatA  ccanlinA  aHHrACC 
v^ttiwuittic  a^ojiiiiic  Buvxxcaa* 

^AtQ^^AAnT  inA 

n/fl 
n/  tt 

n  /o 
11/ tt 

Sff62 

.  Conv  Annie  ccrAAn  Hata  to  huff  at 

'  VfUpjr   /^ppiC  9V1CC11  UBltt  lU  uuxxcx* 

^AtC  Ariiil^iimKAT 

«JW  X7U 

$4b38 

Return  GFO^  CArial  number  or  nointer  to  namA  ctrino 
ixwiuiii  VifCrWO  5Ciiax  iiixjiiucx  ui  puxiiici  uj  jittjiic  auuij^. 

r^At^TYrif  ADfttn 

.11/  a 

n  /tt 
11/ tt 

$ff6e 

Get  cnrifA  imnoe  Hafa 
vjci  dpi  lie  xjiittj^c  uaitt* 

OAiQtrino 
VJcio  u  lliK 

Sclba 

t9W  X  l/tt 

$fe72 

Get  'strinv  innut  from  user 

VJCt  SUlllJ^   llipUL  XlVIXII  U9wl» 

nAtVRM 

n/a 

n  /tt 
11/ tt 

$03  le 

Read  first  VRM  block  into  VRM  cache 

ixwau  xiidi  T  oivx  v/ivAi'^  liiiv/  TijiTX  va^iic* 

vjo  L/ireciury 

n/a 

n/fl 
11/  tt 

$03 9 f 

Go  Hirectorv  to  a  STV*cific  suhHirActoin/ 
vjv  uxxcviuxy  lu  tt  d^i^vtxxw  dui/uixcviuiy* 

ftotoPircf  K^Ami 
vju  lu  ni^  uviciiu 

Sclbd 

$fel8 

Retract  all  sub.menus  and  reactivate  at  main  level 
i\vu aw  oil  auu  iiiwiius  oiiu  icawixvttic  tti  iiiaxii  iwvei* 

vjiapnicso  u 

X  JO 

Sfe60 

pYACIltA  o  ctTincT  of  (TTanhicc  rommanrle 

bACvuic  tt  SIX  Ills  ^k  {^lapiiiva  vununaiius* 

HideOnlyMouse 

n/a 

$c2f2 

$ff7a 

Temporarily  remove  soft-sprite  mouse  pointer. 

Horizontal  Line 

Sells 

$cll8 

$fe27 

Draw  a  patterned  horizontal  line. 

i_BitmapUp 

Sclab 

$clab 

$fe57 

Inline  BiimapUp. 

i_FillRam 

Sclb4 

$clb4 

$ff02 

Inline  FillRam. 

i_FrameReciangle 

Scla2 

$cla2 

$fe42 

Inline  FrameRectangle. 

i_GraphicsString 

SclaS 

$cla8 

$fe63 

Inline  GraphicsString. 

iJmprintRectangle 

Sc253 

Sc253 

$fe51 

Inline  ImprintRectangle. 
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Name  C64      C128     Apple  Description 


i  MoveData 

$clb7 

$clb7 

$fef9 

Inline  MoveData. 

i  NewBitUo 

n/a 

n/a 

$ff9c 

Inline  NewBilUp. 

LPuiSlring 

Sclae 

$clae 

$fe6c 

Inline  PutString. 

i  RecoverRectanKle 

$cla5 

$cla5 

$fe4b 

Inline  RecoverRectanRlc. 

i  Rectanf^le 

$cl9f 

$cl9f 

$fe3c 

Inline  Rectangle. 

ImprintLine 

n/a 

n/a 

$ff8f 

Imprint  horizontal  line  to  background  buffer. 

ImprinlRectanKle 

$c250 

$c250 

$fe4e 

Imprint  rectangular  area  to  background  buffer. 

InfoCard 

n/a 

n/a 

$670f 

Get  I/O  card  attributes. 

InitCard 

n/a 

n/a 

$6700 

Intialize  I/O  card. 

InilForDialoK 

n/a 

n/a 

$ff4a 

Internal  pre-dialog  box  intialization. 

InitForlO 

$c25c 

$c25c 

n/a 

Prepare  CBM  system  for  I/O  across  serial  bus. 

InitForPrint 

$7900 

$7900 

$6000 

Initialize  printer  (once  per  document). 

InitMouse 

$fe80 

$fe80 

$fOOO 

Initialize  input  device. 

InitProcesses 

$cl03 

$cl03 

$feae 

Intialize  processes. 

InilRam 

$cl81 

$cl81 

$ff05 

Initialize  memory  areas  from  table. 

InitSprile 

n/a 

n/a 

$ff32 

Initialize  software  sprites. 

InitTexiPrompl 

SclcO 

$clcO 

$fe78 

Initialize  text  prompt. 

InputByle 

n/a 

n/a 

$6709 

Read  byte  from  I/O  card. 

InseriRecord 

Sc286 

$c286 

$0339 

Insert  new  VLIR  record  in  front  of  cuncnt  record. 

IntemiptMain 

SclOO 

$clOO 

$fe03 

Main  interrupt  level  processing. 

InvcrtLine 

Scllb 

$cllb 

$fe2d 

Invert  the  pixels  on  a  horizontal  screen  line. 

InvertRectangle 

$cl2a 

$cl2a 

$fe45 

Invert  the  pixels  in  a  rectangular  screen  area. 

IrqMiddle 

n/a 

n/a 

$ff20 

Software  interrupts  entry  point. 

IsMselnRej^ion 

$c2b3 

$c2b3 

$fe9c 

Check  if  mouse  is  within  a  screen  region. 

JsrToAux 

n/a 

n/a 

$03b4 

Call  aux -memory  subroutine. 

KeyFiller 

n/a 

n/a 

$f009 

Input  driver  keypress  filter. 

LdApplic 

$c21d 

Sc21d 

$03  8d 

Load  GEOS  application. 

LdDeskAcc 

$c217 

$c217 

$035d 

Load  GEOS  desk  accessory. 

LdFile- 

$c211 

$c211 

$0312 

Load  GEOS  data  file. 

IjoadAuxSet 

n/a 

n/a 

$fn7 

Use  aux-memory  character  set. 

LoadCharSet 

Sclcc 

$clcc 

$fe8a 

Use  main-memory  character  set. 

MainLoop 

$clc3 

$clc3 

$feOO 

GEOS  MainLoop  processing. 

MakeSubDir 

n/a 

n/a 

$0387 

Create  ProDOS  subdirectory. 

MouseOff 

Scl8d 

$cl8d 

$fe96 

Disable  mouse  pointer  and  GEOS  mouse  tracking. 

MouscUp 

$cl8a 

$cl8a 

$fe99 

Enable  mouse  pointer  and  GEOS  mouse  tracking. 

MoveAuxData 

n/a 

n/a 

$ff6b 

Apple  aux-memory  memory  move  routine. 

MoveBData 

n/a 

$c2e3 

n/a 

128  backram  memory  move  routine. 

MoveData 

$cl7c 

$cl7e 

$fcf6 

Memory  move  routine. 

NewBitClip 

n/a 

n/a 

$ff95 

Bit-boundary  BitmapClip. 

NewBitOlherClip 

n/a 

n/a 

$ffOe 

Bit-boundary  BiiOtherClip. 

NewBiiUp 

n/a 

n/a 

$ffld 

Bit-boundary  BitmapUp. 

NewDisk 

Sclel 

$clel 

n/a 

Tell  CBM  disk  turbo  software  that  a  new  disk  is  in  drive. 

NexiRecord 

Sc27a 

$c27a 

$0336 

Make  next  VLIR  the  cuncnt  record. 

NormalizeX 

n/a 

$c2e0 

n/a 

Normalize  CI 28  X-coordinates  for  40/80  modes. 

NxtBlkAlloc 

$c24d 

$c24d 

$0354 

Version  of  BlkAlloc  diat  starts  at  a  specific  block. 

OpenCard 

n/a 

n/a 

$6703 

Open  I/O  card  for  access. 

OpenDisk 

$c2al 

$c2al 

$0399 

Open  disk  in  current  drive. 

OpenRecordFile 

$c274 

$c274 

$033f 

Open  VLIR  file  on  current  disk. 

OuipuiByte 

n/a 

n/a 

$6706 

Write  byte  to  I/O  card. 

Panic 

$c2c2 

$c2c2 

$fef3 

System-error  dialog  box. 

PointRecord 

$e280 

$c280 

$0342 

Make  specific  VUR  record  the  current  record. 

PosSprite 

$clcf 

$clcf 

$fea5 

Position  sprite. 

PreviousRecord 

$c27d 

$c27d 

$0345 

Make  previous  VLIR  record  the  current  record. 

PrinlASCU 

$790f 

$790f 

$600c 

Send  ASCII  data  to  printer. 

PrintBuffer 

$7906 

$7906 

$6009 

Send  graphics  data  to  printer. 

PromptOff 

$c29c 

$c29e 

$fe7c 

Turn  off  text  prompt. 

PrompiOn 

$c29b 

$c29b 

$fe7b 

Turn  on  text  prompt. 

PurgeTurbo 

$c235 

$c235 

n/a 

Remove  CBM  disk  turbo  software  from  drive. 
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GEOS  Quick  Reference 


Apple 

L/cScripiion 

PutBlock 

$cle7 

$cle7 

C  Al  Al 

$0303 

Write  singel  disk  block  from  memory. 

PutChar 

$Cl45 

$Cl45 

SfeSl 

Display  a  single  character  to  screen. 

PutDecimal 

Cm  1  QA 

ChClo4 

5Clo4 

5teof 

Format  and  display  an  unsigned  double-precison  number. 

PulDirrleaa 

^^OA  t> 

«>cz4a 

%bc24a 

C  Al  11m. 

50370 

Write  directory  header  to  disk. 

PutScreenLine 

n/a 

n/a 

5lio5 

Copy  buffer  data  to  Apple  screen  memory. 

PutString 

)Cl4o 

5Cl4o 

5ieoy 

Print  string  of  characters  to  screen. 

PUlVBM 

n/a 

n/a 

CA10  1 

50321 

Flush  VBM  cache;  write  currently  cached  block  to  disk. 

ReadBackLine 

n/a 

n/a 

cm  A 
511/4  . 

Get  data  from  background  screen  in  linear  bitmap  format. 

ReadBlocK 

ScZla 

shc2la 

n/a 

CBM  get  disk  block  primitive. 

ReadByte 

ChCZDO 

OCZDO 

Read  disk  file  a  byte  at  a  time. 

ReadCIocK 

n/a 

n/a 

CAQ  AA 

50oOO 

Update  ObUo  time/date  variables  from  clock  hardware. 

Read  rile 

)ClIi 

5CllL 

CA1  1  < 

50J  ID 

Read  chained  list  of  blocks  into  memory. 

ReadLinx 

CQAy*  U 

Q  Ail  U 

n/a 

DmoJ        f^^\M        CwMmI*   /oMM^MM  IZ^tv 

Keaa  k^dM  tracK/sector  iiruc. 

Read  Record 

$c2oc 

$c2oC 

CA1  O 

50348 

Read  current  VLIR  record  into  memory. 

ReadScanLme 

n/a 

n/a 

5ll95 

Get  data  from  foreground  screen  in  linear  bitmap  format. 

RecoverAllMenus 

5cl57 

$C1D7 

CTmI  M 

5iele 

Recover  all  menus  from  background  buffer. 

RecoverFG 

n/a 

n/a 

CA'5  «M 

503  ae 

Restores  foreground  screen  from  data  created  with  SaveFG. 

RecoverLine 

«hci  le 

Pm  11m 

5ci  le 

5iejo 

Recover  horizontal  screen  line  from  background  buffer. 

RecoverMenu 

JiCl  j4 

C*»1  CA 
v>Cl  J4 

^tei  0 

Recover  single  menu  from  background  buffer. 

RecoverRectangle 

)ciza 

C/*1 

5ie4o 

Recover  rectangular  screen  area  from  background  buffer. 

RecoverSysRam 

n/a 

n/a 

5tl53 

Restore  system  after  dialog  box  or  desk  accessory. 

Rectangle 

Scl24 

Cm  1  i4 

5cl24 

5ie39 

Draw  a  filled  rectangle. 

ReDoMenu 

Scl93 

ff  ^  1  A1 

$cl93 

5iel2 

Reactivate  menus  at  the  current  level. 

Renamerile 

$c23*^ 

Sc2j9 

C  A*!  0*5 

50393 

Rename  ObUo  disk  rile. 

ReOpenDisk 

n/a 

n/a 

C  Al 

503  a2 

Reopen  disk  to  previous  directory. 

ReseiAlarm 

n/a 

n/a 

C  AO  Am 

50oOC 

Disable  clock  driver  alarm. 

ResetHandle 

5cv}03 

CmAAI 

5  c  003 

n/a 

Internal  bootstrap  entry  point. 

RestartProcess 

SclOo 

C  M  1  A^ 

5clOo 

5reDl 

Unblock,  unfreeze,  and  restart  process. 

ResloreFontData 

n/a 

n/a 

c  en  o 

5ir3o 

Restore  font  variables  from  saveFontTab. 

RstrAppl 

Sc23e 

5c23e 

C  A1  ^  A 

50360 

Leave  desk  accessory  and  return  to  calling  application. 

RstrFrmDialog 

Sc2bf 

$c2bi 

$rila 

Exit  dialog  box. 

SaveFG 

n/a 

n/a 

CA1  >U 

503aD 

Save  foreground  screen  data  for  RestoreFG. 

5aveFile 

Scled 

CmI  m,J 

Scled 

CA1  1  O 

503 1 5 

Save/create  a  ObUS  file. 

•  SaveFontData 

n/a 

n/a 

cm< 

Copy  font  variables  to  saveFontTab. 

SetAlann 

n/a 

n/a 

ff  AQ  AA 

50ooy 

Set  clock  driver  alarm. 

SeiDevice 

^CZDU 

5CxD0 

n/a 

Establish  communication  with  a  new  serial  device. 

SetGDirEntry 

$ClfO 

Cm  1  fi\ 

5clrO 

CAO  "7U 

5037D 

Create  and  save  a  new  GEOS  directory  entry. 

SetGEOSDisk 

Sclea 

CmI  mm 

5clea 

.  /m 

n/a 

Convert  normal  CoM  disk  mto  GEOS  format  disk. 

SelLdVars 

n/a 

n/a 

5li47 

Set  internal  Ld  variables  from  GEOS  pseudoregisters. 

SetMode 

n/a 

n/a 

C  ^  A  t  C 

$6015 

Set  print  mode. 

SetMouse 

n/a 

5feoy 

n/a 

Reset  input  device  scanning  circutry. 

SeiMsePic 

n/a 

5c2da 

5rr2i 

Set  and  preshift  new  soft-sprite  mouse  picture. 

SetNewMode 

n/a 

5c2da 

n/a 

Lnange  UbUo  12o  graphics  mode  (40/80  switch). 

SeiNextFree 

ff-^'^  A'^ 

Sc292 

5c292 

CA1U 

5032a 

Search  for  nearby  free  disk  block  and  allocate  it. 

SetNLQ 

57915 

(PT  A  1  < 

$7915 

n/a 

Begin  near-letter  quality  printing. 

SeiPaitem 

$cl39 

$cl39 

5iejo 

Set  current  fill  pattern. 

SetTimeDate 

n/a 

n/a 

C  AO  AiC 

50oOO 

Set  clock  driver  time  and  date. 

SeiUserPattem 

n/a 

n/a 

5lIoO 

ueime  new  ubUo  pattern  image. 

Sleep 

$clV9 

CmI  AA 

5cl99 

5teco 

Put  current  subroutine  to  sleep  for  a  specified  time. 

SlowMouse 

$feo3 

Sfe83 

5  too  J 

Reset  mouse  velocity*  variables. 

SmallPuiChar 

$C2U2 

Cm'^  A*^ 

5c202 

5ievo 

Fast  character  print  routine. 

SoitSprHandler 

n/a 

n/a 

5li2C 

Apple  soft- sprite  drawing  routine. 

SorlAlpna 

n/a 

n/a 

CAI  A< 

50  J  a3 

Insertion  sort. 

StartAppl 

$c22f 

$c22f 

$fe06 

Warmstart  GEOS  and  start  application  in  memory. 

StartASCn 

$7912 

$7912 

$6006 

Begin  ASCII  mode  printing. 

StartMouseMode 

$cl4e 

$cl4e 

$fe93 

Start  monitoring  input  device. 

SiartPrint. 

$7903 

$7903 

$6003 

Begin  graphics  mode  printing. 

StashRAM 

$c2c8 

$c2c8 

n/a 

Transfer  memory  to  CBM  RAM-expansion  unit. 
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GEOS  Quick  Reference 


Name 

C64 

C128 

Apple 

Description 

StatusCard 

n/a 

n/a 

$6712 

Get  current  status  of  I/O  card. 

StopPrint 

$7909 

$7909 

$600f 

End  page  of  printer  output. 

SwapBData 

n/a 

$c2e6 

n/a 

C128  memory  swap  between  front/back  ram. 

SwapMainAndAux 

n/a 

n/a 

$ff71 

Apple  memory  swap  between  main  and  aux. 

SwapRAM 

$c2ce 

$c2ce 

n/a 

CBM  RAM -expansion  unit  memory  swap. 

TempHideMousc 

n/a 

$c2d7 

$ff29  . 

Hide  soft-sprites  before  direct  screen  access. 

TestPoint 

$cl3f 

$cl3f 

$fe24 

Test  status  of  single  screen  point  (on  or  off?). 

ToBasic 

$c241 

$c241 

n/a 

Call  Commodore  BASIC. 

UnblockProcess 

SclOf 

$clOf 

$fcb7 

Unblock  a  blocked  process,  allowing  it  to  run  again. 

UnfrcezeProcess 

Scll5 

$cll5 

$febd 

Unpause  a  frozen  process  timer. 

UpdateMouse 

$fe86 

$fe86 

$f006 

Update  mouse  variables  from  input  device. 

UpdateParent 

n/a 

n/a 

$03  b7 

Update  parent  directory  to  reflect  any  changes. 

UpdateRecordFile 

$c295 

$c295 

$034b 

Update  currently  open  VLIR  file  without  closing  it. 

UpDireciory 

n/a 

n/a 

$03  8  a 

Close  current  directory  and  move  up  one  level. 

UseSystemFont 

$cl4b 

$cl4b 

$fe8d 

Use  default  system  font  (BSW  9). 

VerifyBData 

n/a 

$c2e9 

n/a 

CI 28  backram  verfiy. 

VerifyRAM 

$c2dl 

$c2dl 

n/a 

CBM  RAM-expansion  unit  verify. 

VerticalLine 

$cl21 

$cl21 

$fe2a 

Draw  a  patterned  vertical  line. 

VerWriteBlock 

$c223 

$c223 

n/a 

CBM  disk  block  verify  primitive. 

WarmStart 

n/a 

n/a 

$ff4d 

Bring  GEOS  to  a  warmstart  state. 

WriieBlock 

$c220 

$c220 

n/a 

CBM  write  disk  block  primitive. 

WriieFilc 

$clf9 

$clf9 

$03  lb 

Write  chained  list  of  blocks  to  disk. 

WrileRecord 

$c28f 

$c28f 

$034c 

Write  current  VLIR  record  to  disk. 

NOTES:  The  following  routines  have  had  there  names  changed  to  avoid  confusion  and/or  make  them  unique  in 
the  first  eight  characters: 


Ctfmnt  Namg 

Clocklnt 

CopyLine 

i.NewBitUp 

LoadAuxSet 

MoveAuxData 


Fgrmgrly 

ReadQockInt 

CopyScreenLinc 

i_NewBitmapUp 

LoadAuxCharSet 

MoveBData 


Current  Namg 

NewBitClip 

NewBitUp 

PutChar 

RstrFrmDialog 

SetMsePic 


Fgrmgrly 

NewBitmapClip 

NewBitmapUp 

Putchar 

RstrFrmDialogue 
SetMousePicture 


CBM 


Apple:  The  following  routines  were  not  added  to  the  jump  table  until  version  2.0.3  (version  2.0.  release  3). 
To  call  these  routines  in  v2.0.2  (the  initial  public  release)  requires  a  patch  to  the  jump  ubles. 

NewBitOtherClip,  i.NewBitUp,  AUocatcBloct  GetlstDirEniry,  GetNxtDirEntiy 

The  following  routines  do  not  have  jump  table  entries  in  the  1541  device  driver.  The  device  type  must 
be  checked  before  calling  any  of  these  routines.  Sec  the  actual  routine  reference  for  more  information 
and  1541  alternatives. 

AllocateBlock.  ReadLink 

The  following  routines  do  not  exist  in  version  1.2  and  below  of  CBM  GEOS: 

GetlstDirEntry.  GetNxiDirEntry,  FreeBlock  . 

They  require  calling  directly  into  the  GEOS  Kemal.  See  the  actual  routine  reference  for  more 
information. 
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APPLE  CEOS  «2.0.2  KERNAL  PATCH  (reuision  3) 
Hatt  Loueless 
Robert  Boudidge 
April  6,  1988 

Reuision  History 


ssssssssssssssss 


03/22/88         il/rb    First  hacked  up 

03/23/88         al/rb    Fixed  aux/»ain  snafu 

04/06/88         al/rb    Added  iJeuBitaapUp  for  'ol  uargas. 

04/08/88  aau      Used  oatch  and  aade  aisc  bug  fixes.   Called  routine 

i  NeuBitaaptlp  and  it  seesed  to  work  fine. 
4/18/88  aau      CKanged  references  to  GetNextDirEntry  to  EetHxtOirEntry. 


Notes    This  patch  inforaation  has  not  yet  been  thoroughly  tested.  If  anybody  has  probleas,  please  direct  thea  to  Robert 
and/or  Hatt. 

The  fol loving  routines  were  inaduertently  left  out  of  the  Apple  GEOS  juap  table  in  the  first  production  release  (u2.0,  rel.  !]• 

HevBitOtherClip 
AllocateBlock 
GetlstDirEntry 
GetNxtOirEntry 
i  NeuBitaapUp 


Applications  that  uish  to  use  these  routines  aust  patch  the  Kernal  ]uap  tables  in  order  to  run  under  v2.0,  rel.  2. 
Startino  uith  u2.0,  release  3,  these  routines^are  guaranteed  to  be  in  «he^)uap  table.  Applications  flUST  check  the 


nuaber  Before  patching  in  order  to  be  coapatible  uith  future  versions  of  Apple  GEOS 
The  following  unused  juap  table  slots  uill  be  used' 


version 


HeuBitOtherClip 
AllocateBlock 
GetlstDirEntry 
GetNxtOirEntry 
i  HeuBitaapUp 


SffOe 
I  030c 
i;039i 
i;039c 
$ff9e 


old  ToBasic] 
old  ReadChain) 
old  ChkOkGEOS 
old  SetGEOSOisk) 
old  ageos  RaaDD) 


These  equates  uill  not  change  and  uill  ensure  an  application  is  upuard  coapatible  uith  future  versions  of  Apple  GEOS. 
Patch  info  for  u2.0,  release  2i 


Routine 

sssssss 

HeuBitOtherClip 

AllocateBlock 

GetlstDirEntry 

GetNxtOirEntry 

iJetBitaapUp 


Address 

ssssssm 

IffOe 
030c 
0396 
039c 
ff9e 


In  aux 

ap  Sdf9a 
ap  i45cl 
ap  4e<6 
ap  i4e78 
ap  Panic 


In  aain 

sr  ifcl6 
sr  l0900 
sr  S0900 
sr  i0900 
, sr  iecb3 


aux  >  altzp) 
aux  «  raaurt 
aux  •  raaurt 
aux  •  raaurt 
aux  »  raaurt 


(Note  that  i  NeuBitaapUp  cannot  be  run  uhile  the  alternate  zero  page  (ALTZP JH)  is  suitched  in.  The  juap  table  entry 
juaps  to  the  Panic  routine.  This  routine  aust  be  called  uhen  the  aain  zero  page  is  in.) 

And  in  codes 


;Patch 
ffiiiff 


Patch  GEOS  v2.0.2 


It"  EQUATES 

^Locations  in  juap  table 

HeuBitOtherClip  •  $ff0e 

AllocateBlock  «  $030c 

GetlstDirEntry  -  $0396 

GetNxtOirEntry  '  i039c 

i.HeuBitaapUp  «  $ff9e 

lOirect  entry  points  into  v2.0.2  kernal 

j.NeuBitOtherClip  *  Sdf9a 

oJllocateBlock  ■  i45cl 

0  GetlstDirEntry  «  l4e66 

©"GetNxtOirEntry  •  i4e78 

iT  HeuBitaapUp  «  iecb3 


;pixe1  boundary  version  of  BitOtherClip 

lal locate  block  in  VBH  (opposite  of  FreeBlock) 

iget  1st  directory  entry  in  current  directory 

iqet  next  directory  entry 

100  an  inline  HeuBitaapUp.  Hike  likes  this  call. 


SuitchAllRegs 


mi 


ifor  aux-high  bank  graphics  switch 


fi1e>  kernalPatch,  page  1,  tiK  Tue  Apr  19  12<58:45  1968 


LouSuitch  •  $0900  if or  aux  bank  (low  juip  table) 

GOODJERSION  «  S20  {version  2.0.3  does  not  need  to  be  patched 

GOOOJELEASE  •  $03  ^ 

.■aero  PatchJapTable    dest,  source     (copies  three  bytes  froi  source  to  dest 
Ida  source 
sta  dest 
Ida  source^l 
sta  destM 
Ida  source^2 
sta  dest^2 

.endi 

$Notet  Can  be  lunged  to  use  less  bytes  by  table  driving  the  patch.  Done  this  uay  here  for 
I         demonstration  purposes  only. 

Patch* 

I  Check  version  to  ensure  that  ue  don't  patch  Kernals  that  are  already 

t  fixed,   ye  check  for  version  2.0.3  (good  version)  explicitly  because 

f  2.0.2  is  the  first  release  of  the  Apple  Kernal  and  2.0.3  has  the  fixes 

i  in  it. 

Ida  version 

csp  tGOODJERSION 

bne  10$  'ibranch  if  current  version  >2.0.  If 

I  not  then  it  is  3.xx  uhich  is  fixed. 

Ida  release 

cnp  tGOODJELEASE 

bge  10$  (branch  if  this  release  >*  good  release 

bra  20$  ibra  to  do  the  patch 


10$t 


rts 


fThis  is  a  version  that  needs  to  be  patched.  Go  patch  it. 

ffirst  patch  addresses  in  nain 

20$« 

PatchJMpTbl       NeuBitOtherClip,  n  HeuBitPatch 
PatchJipTbl       AllocateBlock,  fl  AllocBIkPatch 
PatchJnpTbl      GetlstDirEntry,  H  GetlstPatch 
PatchJapTbl       GetHxtDirEntry?  fl'GetNxtPatch 
PatchJipTbl       i.NeuBitiapUp,  fIjNeuBitiapUp 

fpatch  graphics  in  high  auxiliary 

sta  ALTZPJN  I  suit ch  in  high  aux 

PatchJnpTbl      NeuBitOtherClip.  A  HeuBitPatch 
Patch Jap Tb I       i  NeuBitaapUp,  A  iHeuBitaapUp 

sta  AUTZPJFF        "  ;  suitch  out  high  aux 

(patch  others  in  nornal  aux 

sta  RAfiyRTJN  I  send  urites  to  aux  bank 

PatchJnpTbl  .  AllocateBlock,  A  AllocBIkPatch  I  read  froa  aain,  write  to  aux 

PatchJapTbl  GetlstDirEntry,  K  GetlstPatch  \  read  froa  aain,  write  to  aux 

PatchJapTbl  GetNxtDirEntry,  AjetNxtPatch  (  read  froa  aain,  write  to  aux 

sta  RAHURTJFF  I  send  urites  back  to  aain 


99$: 


rts 


fflain  aeaory  patches 
n  NeuBitPatcht 

jsr  SwitchAIIRegs 

n  AllocBlkPatchi 

tl-GetlstPatchi 

nlGetNxtPatch* 

jap  LowSwitch 
n.iNeyBitaapUps 

jap  ii.HeuBitaapUp 

iAux  aeaory  patches 
A.NeuBitPatcM 

jap      j  NeuBitOtherClip 
AJllocBlkPatch" 

jap      0  AilocateBlock 
A  GetlstPatchi  " 
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jip      0  GetlstDirEntry 
flJetHxtPdUh«    "    ,  ^ 

0  EetHxtDirEntry 


lap  o.betnxcuirtniry 
A  iHeuBi{aapUp> 

jip      Panic  5can't  call  this  routine  froi  aux  •e«ory. 


This  page  Intentionally  left  blank  to  maintain  right/left  (verso/recto) 
page  ordering.  Final  version  will  correct  this. 


Mtn^t  R^'ftin'^''  (^niirth  f*'*  '  "'^l )  5/2/88 
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GEOS  Text  Escape  Character  Codes 


Code     Constant  Description 


0 

NULLV 

String  termination  character. 

1 

unused 

2 



unused 

3 

unused 

4 

J 

unused 

D 

6 

t 

unused 

7 

unused 

8 

BACKSPACE 

erase  tne  previous  cnaracter  (APP^g  vjcuo  uses  me  wiain  ui  lasiwiain;. 

9 

rORWARDSrALb 

rfot  unpiemenieci  in  kjcUo  oh  or  %jt,uo  i^o.  iviovc  current  pruiung 
position  rightwaid  the  width  of  a  space  character.  This  escape  code  is  used 

K\/  oAnVk/ritA  tn  ri*nrf»c^nf  A  tnH           TAR  cnnctflnt^ 

10 

LF 

Linefeed:  move  current  printing  position  down  one  line  (value  in 
currentHeight). 

1 1 

HOME 

Move  current  printing  position  to  upper-left  screen  comer. 

12 

T  mf  Txrr? 

UPLINE 

Move  current  printing  position  up  one  line  (value  in  currentHeight). 
inis  escape  cooe  is  usevi  oy  geoTYmc  lo  represeiii  a  pagc-urca&  ^uac 
PAGE  BREAK  constant). 

1  D 

carnage  reium.  move  currcni  priiiLijig  posiuon  uowii  une  iinc  oiiu  uvci  w 
the  left  margin  (value  in  leftMargin). 

1  A 

T^AOin  iinHArlinmfy 

OCJ^lIl  UllUCillllUI}^. 

15 

UUNEOFF 

End  underlining. 

16 

ESC.GRAPfflCS  ¥ 

Escape  code  for  graphics  string:  remainder  of  this  string  is  treated  as  input 
lO  uie  vvrapnicsoirinK  rouiine. 

1  / 

unintp lenient ed  This  escape  code  is  ignored  by  GEOS  text  routines.  This 

ACCiinA   ccsAa   ic   iice<l   Hv    o^cs^^ryt^   Xf\   rAnrpcAnt    a   nilAr   Acr^anA  ^iicp 

ESC  RULER  constant). 

18 

REVON 

Begin  reverse  video  printing  (white  on  black). 

19 

REVOFF 

End  reverse  video  printing. 

20 

GOTOX  Y 

Change  the  x^coordinate  of  the  current  printing  position  to  the  word  value 
stored  in  the  following  two  bytes. 

21 

GOTOY  ¥ 

Change  the  y-coordinate  of  the  current  printing  position  to  the  byte  value 
in  the  following  byte. 

22 

GOTOXY  ¥ 

Change  the  x-coordinate  of  the  current  printing  position  to  the  word  value 
stored  in  the  following  two  bytes  and  change  the  y-coordinate  to  the  value 
in  the  third  byte. 

23 

NEWCARDSET  ¥ 

unimplemented.  This  does  nothing  but  skip  over  the  following  two  bytes. 

24 

BOLDON 

Begin  boldface  printing. 

25 

ITAUCON 

Begin  italicized  printing. 

26 

OimiNEON 

Begin  outlined  printing. 

27 

PLAINTEXT 

Begin  plain  text  printing  (turns  off  all  type  style  attributes). 

28 

t 

unused 

29 

t 

unused 

30 

t 

unused 

31 

t 

unused 

tshould  never  be  sent  to  a  GEOS  text  routine  unless  the  application  is  running  under  a  future  version  of 
GEOS  that  explicitly  supports  this  character  code. 
^For  use  with  PutString;  not  directly  supported  by  PutChar. 
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GEOS  ASCII  Character  Codes 


Code 

Character 

Code 

Character 

32 

space 

65 

A 

97 

a 

33 

1 

66 

B 

98 

b 

34 

n 

67 

C 

99 

c 

35 

# 

68 

D 

100 

d 

36 

$ 

69 

E 

101 

e 

37 

% 

70 

F 

102 

f 

38 

71 

G 

103 

39 

1 

72 

H 

1  /\A 

104 

h 

40 

( 

73 

I 

105 

i 

41 

) 

74 

J 

106 

i 

A  O 

42 

75 

K 

107 

k 

43 

+ 

76 

L 

108 

1 

A  A 

44 

77 

M 

109 

m 

A  C 

45 

78 

N 

110 

n 

46 

79 

0 

111 

0 

47 

80 

P 

112 

i4  O 

48 

U 

81 

9 

113 

q 

4y 

1 

82 

R 

11/1 
114 

r 

50 

2 

83 

S 

lie 

115 

s 

51 

3 

84 

T 

116 

t 

52 

A 

4 

85 

U 

117 

u 

53 

5 

86 

V 

1  1  o 

lis 

V 

j4 

0 

87 

W 

110 

w 

55 

7 

88 

X 

IZU 

X 

56 

8 

89 

Y 

121 

y 

57 

9 

90 

Z 

122 

z 

58 

91 

[ 

123 

f 

59 

92 

\ 

124 

1 

60 

< 

93 

1 

125 

) 

61 

94 

A 

126 

62 

> 

95 

127 

deletion  character 

63 

7 

96 

USELAST 

64 

(a 

128 

short-cut  key: 

SHORTCUT 

2 
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■  > 


iifi  UPDATES     PREUIOUS  PATCH  INFORHflTION  HAD  BANK  INFORHATION  SUITCHED 
iiif  USE  THIS  VERSION  TO  PATCH  KERNAL  AND  DISREGARD  EARLIER  i«>i 

APPLE  GEOS  V2.0.2  KERNAL  PATCH  (revision  2) 
Hatt  Loveless 
flarch  23,  1988 

Note:    This  patch  inforaation  has  not  yet  been  thoroughly  tested.  If  anybody  has  problens,  please  direct  then  to  Robert 
and/or  Hatt, 

The  following  routines  were  inadvertently  left  out. of  the  Apple  GEOS  jump  table  in  the  first  production  release  (u2.0,  rel.  2) 

NeuBitOtherClip 
AllocateBlock 
GetlstOirEntry 
GetNextDirEntry 

Applications  that  wish  to  use  these  routines  Must  patch  the  Kernal  junp  tables  in  order  to  run  under  v2.0,  rel.  2. 
Starting  with  v2.0,  release  3,  these  routines  are  guaranteed  to  be  in  the  juap  table.  Applications  tlUST  check  the  version 
nunber  before  patching  in  order  to  be  conpatible  with  future  versions  of  Apple  GEOS. 

The  following  unused  junp  table  slots  uill  be  used> 


NeuBitOtherClip  iffOe 

AllocateBlock  i050c 

GetlstOirEntry  i0396 

GetNextDirEntry  $039c 


old  ToBasic) 
old  ReadChain) 
old  ChkDkGEOS) 
old  SetGEOSDisk) 


These  equates  uill  not  change  and  uill  ensure  an  application  is  upward  conpatible  with  future  versions  of  Apple  GEOS. 
Patch  info  for  v2.0,  release  2* 

Routine  Address  In  aux  In  nain 

8ZSSSSS  SSSSS3X  SSS3Z3SSS  SSSSSSSS 

NeuBitOtherClip  SffOe  m  Sdf9a  isr  SfcK  (aux  »  altzp) 

AllocateBl&ck  i030c  Imp  i45cl  Isr  i0900  aux  *  ranwrt) 

GetlstOirEntry  40396  pp  f4e66  jsr  i0900  aux  «  raaurt 

GetNextDirEntry  $039c  jnp  $4e78  jsr  ^0900  (aux  «  raniwrt) 

And  in  codes 

;ffii«i«ifliffffiiiiiffiiiiiiiiiiiiiif fiiif iiffiiffiiiiiiif«iiiiiit««i«iiii«ifiiitfifiiiiiiiffiiifiifi« 

HewBitOtherCIip  »  iffOe  ;pixel  boundary  version  of  BitOtherClip 

AllocateBlock  '  i030c  lal locate  block  in  UBI1  (opposite  of  FreeBlock) 

GetlstOirEntry  «  f0396  ;get  1st  directory  entry  in  current  directory 

GetNextDirEntry  »  $039c  5get  next  directory  entry 

fOirect  entry  points  into  u2.0.2  kernal 

j  NeuBitOtherClip  -  idf9a 

0  AllocateBlock  >  i45cl 

0  GetlstOirEntry  *  Ue6i 

oJetNextOir Entry  »  $4e78 

SuitchAllRegs  "  ^fcl6  ;for  aux-high  bank  qraph^ics  switch 

LowSwitch  '  $0900  ;for  aux  bank  (low  junp  table) 

GOOD  VERSION  '  $20  iversion  2.0.3  does  not  need  to  be  patched 

GOODlRELEASE  «  $03 

.nacro  PatchJapTable    dest,  source     icopies  three  bytes  froa  source  to  dest 

Ida  source 

sta  dest 

Ida  source*! 

sta  dest*l 

Ida  source*2 

sta  dest*2 

)  .endn 


iNote:  Can  be  nunged  to  use  less  bytes  by  table  driving  the  patch.  Done  this  way  here  for 
I         demonstration  purposes  only. 

Patch? 

fCheck  version  to  ensure  that  we  don't  patch  Kernals  that  are  already  fixed 
Ida  version 
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bq^  m  ibranch  if  current  version  >«  good  version 

Ida  release 

cap  IGOOOJELEflSE  ,  ^  , 

5g^  J9]  ;branch  if  current  release  >«  good  release 

;Thi5  is  a  version  that  needs  to  be  patched.  Go  patch  it. 
;fir5t  patch  addresses  in  Haln 

"^PatchJalpTbl       NevBitOtherClip,  fl  NeuBitPatch 

PatchJwpTbl       flllocateBlock,  H  ftTlocBIkPatch 

PatchJmpTbl       GetlstDirEntry,  A  GetlstPatch 

PatchJapTbl       GetHextOirEntry,  RjetNextPatch 

5Datch  qraphics  in  high  auxiliary  ^        l  .   c.  l 

PatchJrapTbl      NeuBitOtherClip,  flJeuBitPatch 

sta       .         flLTZPJFF  5  switch  out  high  aux 

5patch  others  in  nor.al  aux^^^  ^  ^^^^  ^^.^^^  ^^^^^ 

PatchJmpTbl      flllocateBlock,  fl  flllocBlkPatch  5  read  froa  aain,  urite  to  aux 

PatchJapTbl      GetlstOirEntry,  ff  JetlstPatch  ;  read  froa  aain,  urite  to  aux 

PatchJapTbl       GetHextOirEntry,  flJetNextPatch  I  read  froa  aain,  write  to  aux 

RfltliiRT  OFF  «  send  writes  back  to  aain 


99$: 


sta 


rts 


;Hain  aemory  patches 
(1  NeuBitPatch: 

jsr  SuitchflllRegs 

n  flllocBlkPatch: 

nletlstPatch: 

n"GetNextPatch: 

jap  LowSuitch 

;ftux  aeaory  patches 
fl  NeuBitPatch:    .  ^  _  .  .  ... 
imp       ]  NeuBitOtherClip 

fl  flllocBlkPatch: 


jnp      0  flllocateBlock 
flJetlstPatch:    "    ^   ^.  ^ 

*  jap      0  GetlstOirEntry 
fl  GetHextPatch: 

jmp      0  GetHextOirEntry 


files  forfipplications/diskRH,  page  0,  time  Hon  Feb  22  10:22:24  1988 
Summary  of  desired  disk  read/write  operations  and  what  routines  to  call 


Read  a  block  from  disk  into  FlfllN  memory,  qiuen  block  number 

ReadBlock  or  GetBlock  with  RUbank  set  to  SHAIN  (default) 

Read  a  block  from  disk  into  DUX  memory,  given  block  number 

ReadBlock  or  GetBlock  uith  RVbank  set  to  lAliX  (set,  call,  reset) 

ilrite  a  block  from  HfllN  memory  to  disk,  given  block  number 

UriteBlock  or  PutBlock  uith  RUbank  set  to  IIII^IN  (default) 

Urite  a  block  from  AUX  memory  to  disk,  given  block  number 

yriteBlock  or  PutBlock  uith  RUbank  set  to  tflUX  (set,  call,  reset) 

Read  (and  execute,  if  possible)  a  SEQUENTIAL  file  into  HRIH  memory,  given  its 
filename 

GetFile  uith  RVbank  set  to  miH  (default) 

Reed  a  SEQUENTIAL  data  file  into  AUX  memory,  given  its  filename  (filename  must 
be  in  nAIN)  (note:   datafiles  only?  cannot  read  Desk  Accessories  or  Applications 
into  AUX  and  have  them  execute) 

GetFile  uith  RUbank  set  to  tAUX  (set,  call,  reset) 

Read  a  SEQUENTIAL  file  into  flAIN  memory,  given  its  directory  entry 
LdFile  uith  RUbank  set  to  inAIN  (default) 

Read  a  SEQUENTIAL  file  into  AUX  memory,  given  its  directory  entry  (directory 
entry  must  be  in  flAIN) 

LdFile  uith  RUbank  set  to  lAUX  (set,  call,  reset) 

Open  a  VLIR  file  and  read  (and  execute,  if  possible)  it's  first  record  into 
HhIN  memory,  given  its  filename 

GetFile  uith  RUbank  set  to  SHAIN  (default) 

Open  a  ULIR  data  file  and  read  it's  first  record  into  AUX  memory,  given  its 
filename  (filename  must  be  in  tIAIN)  (note:   cannot  run  OA's  or  ftpplic's  in  AUX) 
GetFile  uith  RUbank  set  to  DhUX  (set,  call,  reset) 

Read  current  ULIR  record  into  flAIN  memory 

ReadRecord  uith  RUbank  set  to  ttlAIN  (default) 

Read  current  ULIR  record  into  AUX  memory,  given  record  number 
ReadRecord  uith  RUbank  set  to  im  (set,  call,  reset) 

Read  a  single  VLIR  record  into  RAIN  memory,  given  record  number 

PointRecord  then  ReadRecord  uith  RUbank  set  to  tllAIN  (default) 

Read  a  single  VLIR  record  into  AUX  memory,  given  record  number 

PointRecord  then  ReadRecord  uith  ftUbank  set  to  |AUX  (set,  call,  reset) 

Read  a  single  VLIR  record  into  nAIN  memory,  given  block  number  of  record's 
index  block  (must  handle  VLIR  variables  yourself) 
Readhle  uith  RUbank  set  to  inAIN  (default) 

Read  a  single  VLIR  record  into  AUX  memory,  given  block  number  of  record's 
index  blocR  [must  handle  VLIR  variables  yourself) 
ReadFile  uith  RUbank  set  to  lAUX  (default) 

Urite  an  indexed  'chain'  from  HAIN  memory,  given  a  pre-al located  index  table 
(in  internal  indexBlock  buffer) 

UriteFile  uith  RUbank  set  to  tllAIN  (default) 

Urite  an  indexed  'chain'  from  AUX  memory,  given  a  pre-al located  index  table 
(in  internal  indexBlock  buffer) 

UriteFile  uith  RUbank  set  to  lAUX  (set,  call,  reset) 

Urite  a  file  from  flAIN  memory,  given  the  header  block  for  it 
SaveFile  uith  RUbank  set  to  ItlAIH  (default) 

Urite  a  file  from  AUX  memory,  given  the  header  block  for  it 
SaveFile  uith  RUbank  set  to  tAUX  (set,  call,  reset) 

Urite  current  VLIR  record  from  RAIN  memory 

UriteRecord  uith  RUbank  set  to  StIflIN  (default) 

Urite  current  VLIR  record  from  AUX  memory,  given  record  number 
UriteRecord  uith  RUbank  set  to  lAUX  (set,  call,  reset) 


.7  * 


reset) 
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Specifications  proposal  for  inplementation  of  /SYSTEH  directory 


10/27/87 


All  disks  from  uhich  the  flppIeGEOS  DeskTop  runs  an  application  will 
either  already  have  a  /SYSTEM  directory  or  have  one  created.   The  /SYSTEM 
directory  (a  subdirectory  nawed  SYSTEM  of  the  root  directory)  is  a  special 
GEOS  subdirectory  where  systea  data  files  (files  of  type  SYblEM,  scraps,  and 
fonts),  desk  accessories,  and  applications  can  reside.   In  addition  to  the 
/SYSTttt  directory,  these  kinds  of  files  can  also  reside  anywhere  else  on  any 
other  directory  on  the  disk. 


Kernals 

The  kernal  support  planned  for  the  /SYSTEM  directory  is  in  the  routine 
OpenOisk.   In  addition  to  its  normal  function,  OpenOisk  will  also  find  the 
/System  direcotry  and  store  the  block  number  of  it's  key  block  in  the  global 
variable  sysDirBlkno.   If  there  is  no  /SYSTEM  directory  found,  a  0  wilt  be 
returned  in  this  word. 

Another  place  where  kernal  support  laiqht  be  needed  is  with  Desk 
Accessories.   Uhen  a  desk  accessory  is  run,  it  will  be  assumed  that  the 
current  directory  will  be  the  directory  with  the  desk  accessory  (i.e.  that 
the  Desktop  and  applications  will  do  a  GoOirectory  before  LdOeskAcc  or  GetFile). 
If  no  change  are  made  to  the  desk  accessory  routines,  the  OA's  Swap  File  will 
be  saved  to  the  current  directory.    If  the  desk  accessory  were  to  change  the 
current  directory,  then  when  RstrAppl  is  called,  RstrAppI  will  not  know  where 
to  find  the  Swap  File.   The  solution  to  this  is  to  always  save  and  load  the 
Swap  File  to/from  a  fixed  location,  either  the  /SYSTEM  directory  or  the  root 
directory.   This  will  require  that  both  LdOeskAcc  and  RstrAppl  make  calls  to 
GoOirectory  to  make  to  the  root  directory  or  the  /SYSTEM  the  current  directory. 
Unfortunately,  this  will  increase  overall  desk  accessory  access  time. 


Applications: 

Application  handling  of  the  /SYSTEM  directory  is  flexible.   It  is  up 
to  each  application  to  determine  how  much  support  for  the  /SYSTEM  directory 
is  necessaru.   For  example,  if  scraps  are  supported,  then  they  should  be  saved 
and  loaded  from  the  /SYSTEM  directory.   This  is  not  mandatory,  as  the  saving 
and  directory  oanrpulation  must  be  done  by  the  application,  but  this  allows 
other  applications  to  find  them.   To  actually  save  something  to  the  /SYSTEM 
directory  will  be  very  simple.  Merely  use  the  following  code: 


Pushy  curKBlkno 

MoveV  sysDirBlkno, rO 

isr  GoOirectory 
txa 

bne  ErrorHandle 

(set  up  registers  for  SaueFile) 

isr  SaveFile 
txa 

bne  ErrorHandle 

Popy  rO 

isr  GoOirectory 
txa 

bne  ErrorHandle 


fsave  current  directory 
•goto  to  /SYSTEM  directory 

•check  for  errors! 


•fSave  file  to  /SYSTEM  directory 

icheck  for  errors! 

;pop  saved  curKBlkno  into  rO 

•return  to  original  directory 

•check  for  errors! 


For  fonts  and  desk  accessories,  an  application  also  has  a  choice  of 
using  any  directory  or  group  of  directories  ic  wants.   However,  to  be  consistent 
with  other  appUcations  it  is  suggested  that  only  the  current  directory  and  the 
/SYSTEM  directory  be  used.  Then,  when  a  font  or  desk  accessory  is  to  be  loaded, 
the  above  code  could  be  used  by  replacing  SaveFile  with  GetFile.  GetFile  will 
automatically  determine  whether  to  use  LdOeskAcc  or  LdFile. 

yhen  an  application  wants  to  gather  a  list  of  desk  accessories  (for  the 
GEOS  menu)  or  fonts  available,  it  wilt  have  to  do  a  FindFTypes  with  both  the 
current  directory  and  the  /SYSTEM  directory.   Since  the  /SYSTEM  directory  is 
known  from  the  global  variable  sysDirBlkno,  this  is  an  ideal  situation  to  use 
the  new  Kernal  routine  FdFTypesInOir  which  searches  in  a  given  directory.  The 
application  will  have  to  keep  track  of  which  of  the  files  it  finds  are  from 
the  /SYSTEM  directory  and  which  are  from  the  current  directory  so  it  can  switch 
to  the  correct  directory  when  it  wants  to  load  an  arbitrary  file  from  the  list. 
The  sample  application  will  handle  this  for  the  desk  accessories  in  the  GEOS 
menu.   This  will  probably  be  all  that  most  applications  will  need. 
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fin  application's  data  files  can,  of  course,  be  loaded  and  saued  to  any 
directory  that  the  application  desires,  but  again,  for  consistency,  only  the 
current  directory  should  be  used.   Uhen  opening  a  data  file  at  the  start  of  an 
application,  the  standard  NEyDBGETFILES  dialog'box  routine  can  be  used.  The 
desktop  will  aaintain  this  interface  by  going  to  the  directory  of  a  data 
file  that  is  double-clicked  on  uhen  the  parent  application  is  launched. 


Desktop** 

The  Desktop  will  deal  uith  the  /SYSTEH  directory  to  a  greater  extent 
than  either  the  Kernal  or  applications. 

In  addition  to  hauing  to  nanaqe  the  list  of  Desk  Accessories  in  the 
GEOS  menu  and  setting  of  the  current  directory  for  double-clicked  data  files 
mentioned  aboue,  the  desktop  will  also  have  to  create  the  /SYSTEfl  directory 
if  none  exists,  manage  a  list  of  applications  for  a  new  menu  item,  handle 
dialog  boxes  with  application  and  desk  accessory  selection  boxes  for  new 
uieu-By-text  modes,  and  qettina  printer  drivers,  input  drivers,  preference, 
and  configuration  files  from  tne  /SYSTEH  directory. 
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Interleauing  issues 


\  The  Main  issue  uith  reading  and  writing  files  is  whether  we  will  be 

'  able  to  'catch  the  interleave',   ft  ProOOS  disk^s  physical  sectors  are 
contiguous,  but  a  ProDOS  block,  which  is  Biade  up  of  two  sectors  has  both 
inter-block  interleauinq  and  intra-block  interleauing.  Inter-block 
interleauing  seperates  the  two  sectors  of  each  block  by  a  single  sector. 
Intra-block  interleauing  seperates  the  two  sectors  of  a  block  (in  addition  to 
the  inter-block  interleauinq  sector  in  between  theml  by  a  single  sector. 

The  disk  spins  at  300  rpm  and  the  ftpple  650l  runs  a  1  Hhz  so  there  are 
200,000  cycles  per  reuolution.   fit  16  sectors  per  track,  this  works  out  to 
about  12,500  cycles  per  sector.   This  means  that  we  haue  about  12,500  cycles  to 
process  both  between  fetching  the  two  sectors  of  a  block  (while  we're  in  the 
deuice  driver)  and  between  fetching  contiguous  blocks  (while  in  the  read  and 
write  file  routines). 

The  deuice  driuer  is  such  that  there  will  be  uery  little  tifine  to 
process  data  if  the  interleave  is  to  be  taken  aduantage  of.  This  means  there 
must  be  uery  little  overhead  between  calls  to  ReadBlock  (or  one  of  the  related 
routines)  during  Readfile  or  between  calls  to  llriteBlock  during  llriteFile. 

The  obuious  solution  is  read  or  write  blocks  directly  to  the 
destination  address  or  directly  from  the  source  address.   The  problen  with  this 
is  that  if  complete  blocks  are  read  into  a  destination  buffer,  bytes  after  the 
end  of  the  buffer  will  be  trashed  if  the  buffer  is  not  a  multiple  of  the  block 
and  the  size  of  the  ualid  data  in  the  file  being  read  is  the  sane  size  as  the 
buffer.  ^ 

The  method  used  by  appleGEOS  ReadFile  eliminates  this  Droblem  and  still 
can  read  blocks  directly  into  their  destination.  Since  a  complete  list  of  the 
blocks  in  the  file  is  available  beforehand,  all  blocks  but  the  last  can  be  read 
directly  into  the  destination  while  the  final  block  can  be  read  into  some 
intermediate  buffer  for  partial  copying  to  the  destination.  This  is  done  by 
scanning  ahead  in  the  list  of  file  blocks.   This  allows  us  to  catch  the 
interleave  if  the  blocks  of  a  file  are  contiguous.   For  the  last  block,  there 
will  be  no  more  blocks  to  read,  so  catchinq  the  interleave  is  not  important. 
This  works  with  reading  into  both  the  HfllN'and  flUX  banks  of  memory. 

For  ilriteFile,  such  a  scheme  is  not  possible  because  the  disk  routines 
can  only  write  to  disk  from  ftUX  memory.   Therefore,  every  512-byte  block  of 
flAIN  memory  that  is  to  be  written  to  disk  must  first  be  copied  to  HIGH  memory 
or  AUX  memory.   Vriting  from  RUX  memory  can  be  done  without  missing  the 
interleave  because  no  copying  is  necessary.   But  writing  from  HftlN  memory 
requires  copyinq  of  512  bytes,  which  along  with  the  fact  that  the  deuice  driuer 
has  to  do  work  before  writing  a  block  eliminates  the  possibility  of  catching  the 
interleave. 
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Oeffiory  features  of  file  reading  and  writing  routines 

Kith  the  128K  flpple  couies  the  picture  of  that  128K  mettory  as  t«o 
individual  64K  baniis.   This  liaits  the  use  of  the  memory  because  switching 
between  the  two  banks  in  an  organized  manner  is  non-trivial. 

To  alleviate  this  probiera  and  still  provide  the  flexibility  that  more 
memory  allows,  the  appleGEDS  disk  routines  allowing  reading  and  writing  files 
from  both  the  I1AIN  and  AUXILIARY  banks,   fl  flag,  RHbank,  controls  which  bank 
files  will  be  read/written  to/froia.   Generally,  this  flag  will  be  set  to  flfllN 
for  normal  applications  work. 
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The  GEOS/Comnodore  Block  fli location  Hap  (Bflfl)  is  replaced  uith  the 
ProOOS  Volune  Bit  flap  (VBtl)  in  the  Apple  version  of  GEOS.  The  VBI1  has  the 
same  function  as  the  BflU,  showing  uhich  blocks  on  a  disk  are  allocated  and 
^  uhich  are  free  to  be  allocated.   There  are,  houeuer,  seueral  changes  in  the 
f  allocation  nap  foroiat  and  in  the  routines  that  deal  uith  it. 

The  UBn  is  configured  as  one  or  nore  blocks  on  the  disk  it  naps.  Each 
byte  of  each  block  represents  the  status  of  8  blocks  on  the  disk,   iiithin  a 
byte,  the  bits  are  »apped  HSB->LSB  to  blocks  X->X*7  uhere  X  is  some  nultiple  of 
8.   So,  for  example,  the  first  byte  of  the  UBfl  represents  disk  blocks  0  to  7. 
Each  additional  byte  represents  the  next  8  blocks  on  the  disk. 

The  UBM  is  allotted  at  least  one  block  on  the  disk.   So  euen  if  the  VBH 
reguires  only  35  bytes  (as  it  does  on  a  143K  5.25"  flopoy),  it  use  and  entire 
5iZ-byte  block.   Since  blocks  contain  512  bytes,  this  aiious  a  single  l/Bfl  block 
to  represent  (8«512=j  4096  disk  blocks.   This  is  the  case  for  143.K  5.25' 
floppies  and  800K  3.$'  microfloppies.  Hard  disks,  uith  upwards  of  5  megabytes, 
uili  require  more  than  on  VBH  block. 

In  a  normal  ProDOS  formatted  disk,  the  UBtl  usually  begins  at  block  i. 
For  multiple  block  UBHs,  the  other  blocks  occupy  blocks  sequentially  after 
block  6.  These  blocks  are  allocated  at  format  time,  and  the  size  or  a  disk 
is  fixed,  so  there  can  be  no  problem  uith  ever  needing  to  allocate  more  VBM 
blocks. 

Therefore,  the  differences  between  the  ProOOS  UBfl  and  the  Commodore  Bflfl 
are  its  location,  its  possible  size,  and  its  format.  The  location  of  the  VBfl 
is  not  in  the  directory  header.  The  size  of  the  VBfl,  although  fixed  for  a 
giuen  drive  type,  is  different  for  different  capacity  driues.   The  VBH  does 
not  contain  a  count  of  free  blocks. 

These  differences  affect  the  GEOS  disk  routines  that  deal  uith  the 
m/m.   These  routines  ares   CalcBlksFree.  FreeBlock,  SetNextFree,  SetlfFree, 
and  FindUBIIBit  (FindBflHBitl.   For  example,  CalcBlksFree  can  no  longer  just 
add  up  the  number  of  free  blocks  per  track  (which  is  stored  in  the  Commodore 
Bflfl).   In  the  Apple  version,  CalcBlksFree  has  to  explicitly  check  each  bit  of 
the  VBfl,  and  do  the  appropriate  calculations  to  determine  the  number  of  free 
blocks  on  a  disk.   It  might  even  have  to  read  in  another  disk  block. 

The  routines,  as  a  group  have  changed  because  of  a  combination  of  two 
of  the  differences,   the  location  and  the  size.  The  routines  now  employ  a  type 
of  cache  for  the  VBtl.   The  routines  have  a  single  block  buffer  in  memory  that 
it  uses  to  hold  the  'current'  VBfl  block.   This  makes  sense  in  multiple«block 
VBHs,  but  uith  143K  5.25'  floppies  and  BOOK  3.5'  microfloppies,  this  buffer 
aluays  holds  the  one  and  only  llBfl  block.  The  routines  aluays  maintain  a  correct 
copy  of  the  current  VBfl  block  in  the  buffer.   Ilheneuer  access  is  needed  to  a 
different  VBfl  block,  the  current  block,  if  it  has  changed,  is  uritten  out  to 
disk  before  reading  in  the  neu  block. 
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Files    flppleSpriteGuide  (128sprtte6uide) 
Author:  Jin  OeFrisco 
Date:    14  January  1987 

Purpose:  This  file  explains  what  needs  to  be  done  to  convert 

the  portions  of  C64  6E0S  applications  that  deal  uith 
sprites  to  run  under  Apple  GEOS. 


Baci^ground  Info: 


The  C64  contains  a  chip  to  handle  sprites  in  hardware. 
Unfortunately,  this  chip  is  not  available  on  the  Apple, 
so  the  functions  of  that  chip  have  been  sinulated  in 
software  that  is  included  in  the  kernal.  Host  of 
the  capabilities  of  the  VIC  chip  haue  been  taken  care 
of,  and  if  you  are  not  doing  exotic  things  uith  sprites 
your  code  nay  work  uith  one  or  tuo  changes. 

The  aaior  changes  include:  sprite  0  (the  cursor)  is 
treated  differently  than  any  other  sprite.  The  code 
for  this  beast  has  been  optiaized  to  get  reasonably 
fast  nouse  response,  uith  a  resulting  loss  in 
functionality.   You  cannot  double  the  cursor's  size  in 
either  x  or  y.  You  cannot  change  the  color  of  the 
cursor.  The  size  of  the  cursor  is  liiited  to  16-pixel5 
uide  and  8  lines  high.  One  added  feature  is  the  ability 
to  add  a  uhite  outline  to  the  picture  that  is  used  for 
the  cursor.  This  allows  it  to  be  seen  while  nouing 
ouer  a  black  background. 

For  the  other  7  sprites,  all  the  capabilities  have  been 
emulated  except  for  color  and  collision  detection.  In 
addition,  the  <4th  byte  of  the  sprite  picture  definition 
(previously  unused]  is  now  used  to  provide  soae  size 
info  about  the  sprite.  This  is  used  to  optiaize  the 
drawing  code. 

To  change  your  code  over,  look  over  the  following  list 
of  possible  problen  areas.  This  list  will  be  updated 
as  Bore  probiens  are  found,  and  you  should  add  an  entry 
when  you  cone  up  with  a  new  one. 


Q 
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Sprite  Problen  Areas: 

To  make  sure  your  sprite  code  «iH  run  under  fippleGEOS,  read  ouer  the 
following  lisl.   If  you  see  a  problen  that  applies  to  your  application, 
take  the  appropriate  corrective  action.   If  you  encounter  a  problen 
that  is  not  listed  belou,  add  a  solution  when  you  cose  up  wich  one  (or 
state  that  a  solution  is  not  possible). 

PROBLEM  SOLUTION 


l/riting  directly  to  the  screen 


Change  the  cursor  picture  (sprite  0) 


Use  a  large  picture  for  the  cursor. 


All  sprite  picture  data 


Since  the  old  sprite  were  handled  with 
hardware,  writing  to  the  screen  uasn^t 
a  problen.   If  you  do  it  (systeiB  calls 
NOT  included),  then  call  'TenpHidedouse' 
before  the  write.  This  will  erase  the 
cursor  and  any  sprites  you  haue  enabled. 
You  don^t  haue  to  do  anything  to  get 
then  back,  this  is  done  autonatically 
during  the  next  eain  loop. 

This  should  be  done  with  the  new  call 
■SettlousePicture'.  The  source  for 
this  routine  is  in  /staff/jim/applegeos/ 
Sprite/softSprites.  There  is  a  liuit  to 
the  size  of  che  cursor  to  16  pixels  wide 
and  8  lines  high,  and  you  cannot  use 
■double  in  x  or  y'. 

You  should  discontinue  using  sprite  0 
for  this.   Uhen  you  need  to  change  the 
arrow  to  something  large,  disable  sprite 
0  and  use  another  sprite  that  tracks  the 
fBousePosition  uariables.   Right  now,  the 
only  way  to  disable  sprite  0  is  to  giue 
it  a  null  picture  or  clear  the  low  bit 
of  mobenble. ,  A  "disable  aouse"  call 
should  be  added  soon. 

All  picture  data  should  be  adjusted  to 
include  the  64th  byte.  This  byte  has 
size  inforoation  that  is  read  by  the 
software  sprite  routines,  euen  if  they 
are  garbage  ualues.  The  foraat  of  this 
byte  is:  nigh  bit  set  iieans  that  the 
sprite  is  no  sore  that  8  pixels  wide 
(this  neans  it  can  be  shifted  7  tines 
and  still  be  contained  in  2  bytes).  The 
rest  of  the  byte  is  a  count  of  the  scan 
lines  in  the  sprite.    You  can  either 
include  this  info  as  part  of  the  picture 
definition,  or  stuff  it  into  the  right 
place  with  sone  special  code. 
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PROBLEfl 


SOLUTION 


Uriting  directly  to  the  VIC  chip 


Reading  ualues  froo  the  VIC  chip 


This  is  generally  ok,  since  the  sprite 
enulation  routines  take  the  position 
and  doubling  info  froa  the  registers  on 
the  VIC  chip,. with  the  exception  of  the 
X  position.  The  VIC  chip  allows  9  bits 
for  X  positions,  uhich  is  not  enough 
for  a  560-wide  screen.  You  should  write 
the  X  position  to  the  qlobal  variables 
•reqXposO,  regXposl...'  (request  x  pos). 
These  are  full  words,  in  consecutive 
locations.  Better  yet,  use  the 
■PosSprite'  call  in  the  kernel. 

This  is  also  ok  for  the  status  ualues 
and  for  the  y  position.  The  x  oosition 
should  be  read  froa  the  reqXposO  regs. 


Using  VIC  chip  collision  detection        There  is  none. 


Uriting  to  the  VIC  chip  for  calling 
PosSpnte,  EnablSorite,  DisablSprire) 
at  interrupt  level 


Turning  the  nouse  On/Off 


Don't  do  it.  Since  the  sprites  are 
drawn  at  aain  loop,  this  causes  subtle, 
irreproducable  tiainq  bugs  that  are 
impossible  to  oet  out.  It  is  all  right 
to  change  the  House's  position  here, 
since  the  aouse  is  drawn  at  interrupt 
level  also. 

The  aouse  cursor  is  the  only  ■sprite' 
that  is  drawn  at  interrupt  level. 
There  is  now  a  byte  (called  offFlag) 
that  is  used  to  tell  the  interrupt  code 
what  the  status  of  the  nouse  currently 
is.  Uhen  TeapHidetlouse  (or  any  graphics 
routine)  is  called,  the  nouse  is  erased 
fron  the  screen.  The  value  $80  is  stored 
in  offFlag  tq.  tell  the  interrupt  code 
not  to  draw  the  aouse.  Uhile  the  value 
in  offFlag  is  $80,  the  aouse  will  NOT  be 
redrawn  or  erased.  Uhen  we  wish  to  have 
the  aouse  redrawn,  we  store  the  value 
^40  in  offFlag,  which  tells  the 
interrupt  code  to  resuae  drawing  the 
aouse.  nain  Loop  stores  this  value  in 
offFlag  when  the  application  returns  to 
it.  A  value  of  $00  In  offFlag  allows  the 
interrupt  code  to  function  noraally 
(erase  and  redraw  the  aouse  whenever 
necessary)  and  is  stored  there  by  the 
interrupt  code. 
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Font  changes' 

Now  the  systet  font  is  located  in  auxilliary  aeiiory.  There  is  plenty  of 
space  on  the  aux  side,  so  the  apolications  uill  probably  want  to  use  it  for 
holding  the  font  data.  Certain  flags  need  to  be  set  to  tell  the  font  routines 
that  the  fonts  are  in  auxilliary  aenory.  If  the  font  is  in  nain  nefBory,  the 
application  should  call  LoadCharSet  as  usual.  But,  if  the  font  is  in  auxilliary 
nenory,  it  should  call  LoadAuxCharSet,  uhich  sets  a  bunch  of  flags  and  uars  for 
the  font  routined. 

Most  of  the  font  uariables  still  exist  in  flppleGEOS.  Three  variables 
lie  in  sain  nenory  where  the  application  can  easily  access  then: 
baselineOffset 
currentSetliidth 
currentHeight 

Tuo  of  the  uariables  lie  in  the  alternate  zero  page: 
currentlndexTable 
cardDataPo inter 

If  the  application  needs  to  access  these.  It  nust  first  do  a  'sta  ALTZP  ON'  and 
then  access  then,  and  then  do  a  "sta  flLTzPJFFV  Remember  that  ALL  of  tHe  aain 
(application)  zero  page  and  stack  is  swapped  out  here,  so  it  cannot  be  accessed 
until  the  'sta  ftLTZPJFF'  is  executed. 
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This  file  contains  the  lany  changes  iade  in  the  dialog  box  routines: 

DBUSRROUTIHE:    He  nou  assune  that  only  ONE  DBUSRROUTINE  call  is  lade 
per  dialog  box.  This  call  is  nou  nade  AFTER  the  icons  are  displayed.  This  nakes 
It  possible  to  use  DBUSRROUTINE  to  put  stuff  up  ouer  the  icons... 

DBGETFILES:       Holding  the  button  doun  on  the  scroll  icon  aakes  the 
scrolling  continue.  Ho  Hui...  Also,  the  buffer  that  holds  the  filenanes  is  in 
auxilliary  tenory,  and  uill  hold  32  filenanes. 

DBGETNflriES:       This  is  exactly  like  DBGETFILES  except  that  the  user 
passes  the  address  of  a  routine  to  load  a  buffer  with  the  nanes  to  be  displayed. 
This  routine  should: 

Clear  out  the  buffer  in  auxilliary  aienory  froa  $7B00  -  $7B50 

Clear  the  hiqh  bit  of  r7H  and  decrenent  r7H  for  each  nane  stuck  in 
the  Duffer. 

Put  up  to  32  file  naaes  in  the  buffer  (starting  at  $7600  in  aux  nen) 

The  names  nay  be  up  to  15  characters  long,  ^  a  null  terninator. 

fl  buffer  can  be  cleared  in  auxilliary  nenory  by  doing  a  'sta  RflHilRT  ON' 
before  the  call  to  ClearRan  and  a  'sta  RfirtllRtJFF'  afterwarls. 

The  Dialog  Box  table  entry  for  this  routine  is  as  follows: 

.byte  DBGETNfinES 

.uord  Address  of  routine  to  get  names 

•byte  xpos.offset  of  file  box  from  corner  of  DB 

.byte  yposloffset  of  file  box  froa  corner  of  DB 


NEUDBGETFILES:  This  routine  has  a  whole  slew  of  fun  new  features... 
You  can  see  the  spec  file  for  a  description.  Here  is  what  you  need  to  know  to 
use  it: 

The  NEUDBGETFILES  dialog  box  puts  up  its  own  OPEN  icon.  But  the 
application  can  treat  it  as  if  it  were  its  own  OPEN  icon. 

The  NEUDBGETFILES  box  returns  the  selected  file  naae  in  the  same  Banner 
as  DBGETFILES  does...  It  also  returns  the  directory  block  in 
which  the  file  lies  in  the  global  variable  curKBlkno. 

The  NEUDBGETFILES  table  entry  is  of  the  following  format: 

.byte  NEUDBGETFILES 

.byte  file  box  x  offset 

.byte  file  box  y  offset 

.byte  open  icon  x  offset  (bytes) 

.byte  open  icon  y  offset 

.byte  directory  icon/pathnaae  text  x  offset 

.byte  directory  icon/pathnaae  text  y  offset 


ICONS:  There  were  aany  new  system  icons  added  also.  The  complete  list 
is  now: 

CANCEL,flK,YES,NO,OPEN,DISK,ORIVE,QUIT,CREATE  and  IGNORE 

These  can  be  used  by  applications  outside  of  the  dialog  boxes. 
They  lie  in  auxilliary  aemory,  and  their  addresses  are  equated 
to  the  constants:  CANCELJCNJDDRESS.OKJCNJDDRESS,  etc... 

Also,  the  dialog  boxes  nou  allow  16  icons  to  be  displayed! 
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For  PutString! 


ft  change  has  been  aade  in  PutString  to  fix  a  snail  •bug".  In  M4  GEOS, 
?[1^S?C!59  ^loes  not  handle  any  yarqin  faults  (i.e.  If  ue  attewpf  to  print  out 
•»Byni;,  and  only        fits,  PutString  uill  keep  trying  to  output  characters 
until  the  end  of  the  string  is  reached).   Now,  PutString  uill  test  to  see  if 
there  is  a  user  specified  StringFauItVector.  If  not  (StrinqFaultUector  «  SOOOO), 
then  It  uill  put  its  oun  StringFauItVector  in,  uhich  uill  aerely  exit  the 
PutString  routine  when  the  aargin  is  reached. 

ft  change  has  been  aade  in  GetString.  SystenStringSeruice  nou  always 
null-terninates  the  string  in  the  buffer  (i.e.  even  while  the  user  is  inputtinq 
the  string,  it  is  null-terainated). 
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This  file  contains  the  changes  »ade  in  the  icon  and  senu  routines. 
Icons: 

The  icon  pictures  can  nou  be  'double  uidth'  and  can  also  lie  in 
aux  nenory.  Also,  the  icon  routines  currently  noue  the  nouse 
when  they  are  run.  This  option  can  be  disabled.  Uithin  the 
table,  flags  are  set  to  show  that  these  options  are  active. 
These  flags  ares 

.word    XPositionOf House  $Set  high  bit  to  disable  eouse 

;  Boue 

.byte    XJOSJCON  5Set  high  bit  to  signify  that 

Uhe  icon  picture  lies  in 
I'auxilliary  Beaory 

.byte    BytellidthOflcon  ;Set  hiqh  bit  to  signify  that 

;ue  uant  the  icon  data  to  be 
I'double-uidth 


Menus: 

DoHenu  currently  places  the  nouse  ouer  the  nenu  iten  passed 
in  the  accunulator...  Nou,  if  the  ualue  in  the  accunuiator  is 
negative,  the  Doftenu  routine  does  not  noue  the  louse. 
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For  bitnaps: 

There  are  nr-r  :yo  entry  points  to  the  bitmap  routines.  The  old  ones 
still  work  (BitnapCi      BitnapOp.  etc).  There  are  now  also  new  routines  with 
a  new  format  (Neubit:>:-::DCnp,  HeuBitoapUp).  This  fornat  allows  routines  to 
place  bitmaps  on  a  pixel  boundary  and  to  let  a  bitnap  haue  a  pixel  width. 
The  pixel  width  convention  is  as  follows: 

flssuning  a  bitmap  with  a  pixel  width  of  11,  the  first  line  is  represented  by 
X's  and  the  second  line  is  represented  by  Ts;  The  bitmaps  must  lie  in  memory 
as  follows: 

byte  10:  XXXXXXXX 

byte  «1:  XXXUUUUU  ;The  pixel  boundary  lies  within  a  byte 

byte  12:  YYYYYm  ?  so  the  remainder  of  the  byte  will  be 

byte  t3:  YYYUUUUU  ;  ignored  (U  stands  for  unused  bits) 

Also,  the  BitmapUp  routines  allow  the  icons  to  be  doubled  in  width.  To 
use  this  option,  set  the  high  bit  (bit  7)  in  the  high  byte  of  the  pixel  width 
(for  NewBitmapUp)  or  the  high  bit  in  the  byte  width  (for  BitmapUp).  The 
routine  will  double  the  width  of  the  bitmap,  but  not  the  x  coordinate  of  the 
bitmap  .Also,  the  routines  allow  the  bitmap  to  be  in  auxilliary  ram.  To  enable 
this  option,  set  the  high  bit  in  the  x  coordinate. 

The  parameters  that  are  passed  to  the  routines  have  changed.  These 
changes  are  described  here: 

ffff««fi»«ililiifliifiliiiilili«iii«iii««il««i«ilii«««««»«ii«iiliiilifi««li««ii* 

Parameters  for  BitmapUp: 
Pass: 

rO  -  pointer  to  the  bit  mapped  data 

rlL  -  x  byte  position  for  the  bit  mapped  data  (0-69) 

NOTE:   if  bit  7  is  set  in  rlL,  the  bitmap  is  in  aux.  ram 
rlH  -  y  pixel  position  for  the  bit  mapped  data  (0-191) 
r2L  -  wUth  in  bytes  of  the  bit  mapped  data  (0-/0) 

NOTE:   if  bit  7  is  set  in  rzL,  the  icon  is  doubled  in  X 
(bitmap  width  is  doubled) 
r2H  -  height  in  pixels  of  the  bit  mapped  data  (1-192) 

Pass:  (inline) 

.word  dataPointer 

.byte  xCoord 

.byte  yCoord 

.byte  width 

.byte  height 

Parameters  for  NewBitmapUp: 
Pass: 

rO  -  pointer  to  the  bit  mapped  data 
rlL  -  height  in  pixels  of  the  bit  mapped  data  (1-192) 
rlH  -  y  pixel  position  for  the  bit  mapped  data  (0-191) 
r2  -  width  in  pixels  of  the  bit  mapped  data  (0-560) 

NOTE:   if  bit  7  is  set  in  r2H,  the  icon  is  doubled  in  X 
(bitmap  width  is  doubled) 
r3  -  x  pixel  position  tor  the  bit  mapped  data  (0-559) 

NOTE:   if  bit  7  is  set  in  r3H,  the  bitmap  is  in  aux.  ran 

Pass:  (inline) 

.word  dataPointer 
.word  xCoord 
.byte  yGoord 
.word  width 
.byte  height 
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li«liilltl«fii«iilililfffliliif|ffffilf|«||iiliiifiiiiltli«iii|f|«t|«s||«f|||tsi||«t 

Paraneters  for  BitBapCMp: 
Passs 

rO  -  pointer  to  the  bit  Mapped  data 

rlL  -  X  byte  position  for  the  bit  tapped  data  (0-691 

,   ,    NOTEj   if  bit  7  is  set  in  rlL,  the  bitnap  is  in  aux.  ran 
rlH  -  y  pixel  position  for  the  bit  napped  data  (0-192) 
r2L  -  width  in  bytes  of  the  bit  lapped  data  (to  print)  (0-70) 

NOTE*   if  bit  T  is  set  in  r2L,  the  icon  is  doubled  in  X 
(bitnap  width  is  doubted) 
r2H  -  height  in  pixels  of  the  bit  napped  data  (to  print)  (1-192) 

rllL  -  nunber  of  bytes  to  skip  each  row 

rllH  -  number  of  bytes  to  sliip  after  printing  each  row 

rl2  -  nunber  of  lines  to  skip  before  printing 

Parameters  for  NeuBitnapClip-' 

Pass! 

rO  -  pointer  to  the  bit  napped  data 

rlL  -  height  in  pixels  of  the  bit  napped  data  (to  print)  (1-192) 

rlH  -  y  pixel  position  for  the  bit  napped  data  (0-192) 

r2  -  width  in  pixels  of  the  bit  napped  data  (to  print)  (0-560) 

NOTE:   if  bit  7  is  set  in  r2H,  the  icon  is  doubled  in  X 
(bitnap  width  is  doubled) 
r3  -  X  pixel  position  for  the  bit  napped  data  (0-559) 

NOTE:   if  bit  7  is  set  in  rJH,  the  bitnap  is  in  aux.  ran 

rllL  -  nunber  of  bytes  to  skip  each  row 

rllH  -  nunber  of  bytes  to  skip  after  printing  each  row 

rl2  -  nunber  of  lines  to  skip  before  printing 

»ifiiiiii«iiiiii»iiiiiiiiitiii§i«iiiiiiiiiiiifiiiii«iiif  fiifiii«itt«m)iiiiii,iim 
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•iilifilfiiffiiifilillllllfifiliilfililillffflfiff lifffillXliillfiliiilliiS 

ReadBlock 

synopsis 

prouides  the  Apple  equiualent  of  the  Coo»odcre's  lotf  level 
routine 

Authors 

Brian  Chin  February  1988 

Called  by:  ^ 
Pass: 

rl  —  block  nuaber 
r4  —  buffer  address 
RVbank  —  bank  to  use 
Accesses: 

curDriue  —  drive  to  read  block  from 

Returns: 

X  —  disk  error 

Alters: 

y 

Calls: 

GetBlock 

«iiififffi«ifffiiii«iifiiiiiiif«fiiffiiiii«ii«ifffffiif«iiiiiiitiiiii«iifiii 

ReadBlock: 

jmp       GetBlock  ithese  are  equaivalent  routines 
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;iiiiifiiiiiifi<iiifffi«iiffffiiiiiifffiiiiiiffiiiiiiiiifiiii«iiiiiiiii«s«ifis 

s  UriteBIock 
$  synopsis 

;  provides  the  Apple  equivalent  of  the  Comodore's  lou  level 

I  routine 
;  Author: 

;  Brian  Chin  February  198B 

;         Called  by:  ^ 
;         Pass:  • 

I  rl  —  block  nuttber 

;  r4  —  buffer  address 

;  Rybank  —  bank  to  use 

f  Accesses: 

\  curOrive  —  drive  to  read  block  frou 

f  Returns: 
;  X  —  disk  error 

;  Alters: 
;  a,  y 

Calls: 

PutBIock 

iififfiifff<iiii«fffif«i«ii«iiiiffiiiiiiftiififiiiiiiiffifi«iiiii««iftf liiitii 

VriteBlock: 

PushB    nunDiskRetries  ;save  global  retry  count 

LoadB    nuBjOiskRetries.lO         Jset  to  zero  for  no  retries 
isr       PutBIock  ;put  block  to  disk  u/o  retries 

PopB     nunDiskRetries  ;restore  nuaber  of  retries 

rts  ;return  with  error  fron  PutBIock 
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;«ffiiiiiiiififiiffffiiiiffiiiiiiffifiiiiiiiiiiiffiiiiii«iiii«iifi««iifiiiii««f 

;  l/erUriteBlock 
$  synopsis 

I  provides  the  equivalent  of  the  Connodore  GEOS  Kerna] 

;  routine 
Authors 

Brian  Chin  February  1988 

Called  by:  ^ 
Passs 

rl  —  blocli  number 
r4  —  buffer  address 
RUbank  —  bank  to  use 
flccessess 

curDriue  —  drive  to  urite 
nuffiOiskRetries  —  global  retry  count 
Returns: 

X  —  disk  error  status 

filters! 

a,  y 

Calls: 

ReadBlock  (Kernal  routine) 
IfriteBlock  (routine  above) 

lffiffffffil«ff««illf«iiiil«||f|«ili««iff||fiSiiii||iii|f|fiiliifilfiliiflfif 


generalBuf 


VerVriteBlock: 


{address  of  KernaTs  internal  diks  buffer  in 
;         AUXILIflRY  aeaory 


10$: 


90$: 


PushB 
Idx 

Ida 
beq 

PushU 
PushB 
Loady 
LoadB 

PopB 
PopV 
txa 
beq 

dec 

jsr 

txa 
beq 


PopB 
rts 


nunDiskRetries  ;save  global  retry  count 

to  ;assuoe  no  error  in  case  of  no  retries 

nunDiskRetries  ijet  global  retry  count 

90$  tif  no  retries,  do  nothing 

r4  isave  buffer  address 

RUbank  ;save  bank  status 

r4.SgeneralBuf  ;use  Kernal  internal  block  buffer 
RUbank, tflUX 

ReadBlock  ;read  block  to  verify  it 

RUbank     ,  irestore  bank  status 

r4  irestore  buffer  address 

90$  5if  no  error,  exit 

nunDiskRetries  iadjust  retry  count  to  indicate  upcoiing  attenpt 

UriteBlock  icall  our  urite  block  routine  (above)  that 
I        does  no  retries 

10$  ;if  no  error,  Iood  back  to  verify  it 
tif  error,  exit  ioiBediately 


nunDiskRetries 
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iiauic  * 

alarnSetFlao 

PnrMor  1  ii  S 

roiRcr  ly* 

nuurcds  * 

w  1  fcC 

Byte 

Default: 

FALSE 

javcu! * 

No 

Oacr r 1 nf 1 nn  S 

Uc9cr  ipw  luii* 

TPIir  if  thp  fllArn       <pf!  fnr  npn<  fn  nnnitnr    p1<(p  FOI 

Note: 

Name: 

a larnTtttUector 

Ffirtt^r  lui 

1  U 1 Mw 1  »  y 

AdHr^s^: 

nuui 

C64:  §84ad        C128:  $84ad       Aoole:  $0212 

Size: 

Vord 

Default: 

0 

Saued?: 

Yes 

uescr ipv lon* 

dUQic??  or  d  scrviwC  iDUbinc  lur  wne  aidrni  wiuCR  biRic  ouv 

(ringing,  graphic  etc.)  that  the  application  can  use  if 

nprp<cAru 

tlwbk^^Ql  y  » 

Note: 

liU  Ww  * 

Nane: 

alphaFlag 

Formerly: 

• 

Address: 

C64:  $84b4       C128:  $84b4      Apple:  $0225 

Size: 

Byte 

Default: 

0  if  not  gettinq  text  input 

llxxxxxx  if  getting  text  input,  where  xxxxx  are  counter  bits 

Saued?: 

Yes 

uescr ipc lon* 

n^n  fnr  ;i1nhAniimpr ir  ^trinfl  infiut 
r  idQ  lUi  a ipndnuoici  lu  ^wi  in^  mpuv 

bit  0-5  -  Counter  before  pronpt  flashes 

bit  6  '  Flag  indicating  prompt  is  visible 

bit  7  -  Flag  indicating  alphanuiseric  input  is  on 

Note: 

liuulC  ■ 

rinnfldin 

r  r 

Fflrn^r 1u: 

1  u  1  Hci  •  y 

addI  icdtiontlain 

nuui  C^T>  * 

C64:  S849b        C128:  S849b       Apple:  $0200 

Size: 

Hord 

uerauii* 

Saued?: 

No 

Description: 

Vector  that  allows  applications  to  include  their  own  sain  loop 
code.  The  code  pointed  to  by  appftain  will  run  at  the  end  of 
every  EEOS  lainloop. 

Note: 
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Nane: 

backBufPtr 

Foraerlys 

flddresss 

C64:  NA           Ci28:  $131b      Apple:  $9d7c 

Q  1  70  ■ 
W  1  4C* 

16  bytes 

Default: 

None 

Saved?: 

No 

Description: 

Screen  pointer  where  the  back  buffer  cane  from. 
Resides  in  back  ran  of  C128  and  Apple. 

Note: 

Name: 

bakclrO.  bakclrl,  bakclr2,  bakclr3 

For»erIy: 

Address: 

C<4:   $do21  -  4do24  respectiuely 
C12a:  ^do2l  -  sdo24  resoectiuelu 
Apple:  NA 

Size: 

1  Byte  each 

Uetau  It* 

davcuf  * 

No 

nu 

ucscr ip V lun* 

RArknrniinrl  colors  0*3 

nu  wc* 

Name: 

backXBufNuR 

Foraerly: 

Address: 

C64:  NA           C128:  n32b       Apple:  $d98c 

Size: 

8  bytes 

Default: 

Hone 

ddueof  * 

no 

vcscr ip V 1  on* 

For  fiArh  ^nritp    thpr#  W  nnp  hutp  h^rp  for  hou  Bdnu  hutffS 

rUI    cavil           l*Ct    WIICIC    I9   UIIC  uyvc  IICI  C    i  ui     nwv  waiiy  wywb7 

wide  the  corresponding  sprite  is.^  Used  by  C128  and  Apple 

9ulW              VC   iVIU*illC9  QIIU    iC9l            III   VOWR    I  BUi  • 

nu  wc  • 

Naae: 

backYBufHuB 

Formerly: 

Address: 

C64:  Hfl           C128S  $1333      Apples  $d994 

Size: 

8  bytes 

Default: 

None 

Saved?: 

Ho 

Description:      For  each  sprite,  there  is  one  byte  here  for  hou  nany  scanlines 
high  the  corresponding  sprite.  Used  by  C128  and  Apple  soft 
sprite  routines  and  resides  in  back  raa. 

Note: 


Nane:  bootNaeie 
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rorBicr  ly* 

nuui 

c^4:  scoo^       C17A:  ^roo/(      Onnip:  <rnn? 

9  But?^ 

Default: 

6E0S  BOOT 

Saued?: 

Ho 

Description: 

This  is  the  start  of  the  'GEOS  BOOT'  string. 

Note: 

naUK  * 

Foraerly: 

Address: 

C64:  $84af        C128:  $84af      Apple:  $0214 

Size: 

Uord 

Default: 

Coraroodore  -  SCf85 
Apple  -  $FEF} 

Saved?: 

Yes 

Descr  iot ion: 

Vector  to  the  routine  that  is  called  uhen  a  RRK  in^t:riirf inn  i< 
encountered.   The  default  is  to  the  operating  systeia 

'^u^tpii  Prrnr'  Hitilnfi  hnv  rniitinp 
wy^wcii  bi  1  UI     uiaiuu  uua  iuuviiic* 

no  vc* 

naioc  * 

hif  iipr 
UK  vcu 

Forner  tu* 

Address: 

iiu  w  1  www 

C64:  $0916        C128:  i316        Aoole:  NA 

WW*          Y"^***                        W4fcW         y^*W                         IllrlrlW  lilt 

Size: 

Uord 

Default: 

???????? 

Saued?: 

No 

Description: 

BRK  instruction  uector  for  uhen  ROfls  ar?  switched  in. 

Note: 

Nafoe: 

basel ineOffset 

rnrnpr  1  ii  s 
1  ui  ifici  1  y  * 

nuui * 

C^d:                C128:  £76          floole:  §0218 

Size: 

Byte 

Default: 

$06  -  for  BSy  9  font 

daUcUf* 

ICS 

UC^bl  1  U  V  lull  * 

Offset  frnn  tnn  line  to  hA<p1inp  in  character  <pt    i  p  \t 

U  i  1  9C«    1  I  UHI    WUU    1  1  liw    WU    Ua^C  llllw    lit    wtiuiow           9C  b*     ItCt  IV 

changes  as  fonts  change. 

Note: 

Nane: 

CPUJATA 

For»er1y: 

Address: 

C64:  $0001        C128:  NA          Apple:  NA 
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Size5 
Default: 
Saved?! 
Description! 


Uord 

RAnj4K  ($30) 
No 

Address  of  6510  data  register  that  controls  the  hardware  nenoru 
nap  of  the  C64.   The  following  constants  are  used  with  CPU.DfiTA. 


Value 

10  IH 
RAH  64K 

KRNU  BAS  10  IN 
KRNnO  TN  " 


dapping 

<0K  RAH,  4K  I/O  space 
64K  RAH 

both  Kernal  and  basic  ROtIs  napped  into  s^ory 
Kernal  ROM  and  I/O  space  napped  into  menory 


Note! 


Name! 

Foraerly! 

Address! 

Size! 

Default! 

Saved?! 

Description! 

Note! 


CPUJOR 

C64!  $0000        C128!  NA  Apple:  NA 

Byte 


No 


address  of  6510  data  direction  register 


Nane: 

Foriaerly! 

Address: 

Size: 

Default! 

Saved?: 
Description: 

Note: 


cardDataPntr 
cardOataPointer 

C64:  $2c  C128:  $2c         Apple:  $60 

Uord 

Coottodore:  $D2DC  -  for  BSil  9  font 
Apple:  $0150  -  for  BSU  9  font 

Yes 

This  is  a  pointer  to  the  actual  card  graphics  data  for  the 
current  font  in  use 


Naote: 
Fornerly: 
Address: 
Size: 

Default: 

Saved?: 

Description: 

Note: 
Nane: 


curDirHead 


C64:  $8200        C128!  $8200      Apple:  $FA80 

Conaodore  -  256  bytes 
Apple  -  39  bytes 

$00 

No 

For  Coflttodore,  it  is  the  buffer  containing  header  infomation 
for  the  disk  in  currently  selected  drive. 
On  the  Apple,  curOirHead  contains  the  header  of  the  current 
directory.   Initialized  to  all  zeros. 


curDevice 
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Formerly! 

Address! 

C64:  m          C128:  $ba         Apple:  NA 

Size! 

Byte 

Default! 

Comaodore  «  $08 

Saved?! 

No 

Description! 

This  holds  the  current  serial  deuice  number.  See  curDrive 
for  Bore  information 

Note! 

Nane: 

curDriue 

For«erly! 

Address! 

Ci4!  $8489        C128:  $8489      Apple:  $F<Od 

Size! 

Byte 

Default! 

Commodore  -  $08 
Apple  =  $00 

Saued?! 

No 

Description! 

Holds  the  deuice  number  of  the  currently  actiue  disk  drive. 
For  Commodore,  allowed  values  are  8  -  11.   For  Apple,  drives 
are  numbered  0-3. 

Note! 

Name! 

curEnable 

Fornerly! 

Address! 

C64!  NA            C128:  $1300       Apple:  $0951 

Size! 

Byte 

Default! 

None 

Saued?! 

No 

Description! 

This  is  an  image  of  the  C<4  mobenble  register.  Used  for  C128 
and  Apple  soft  sprites. 

Note: 

Hairie! 

curHeight 

Foroerly! 

currentHeight 

Address! 

C64:  $29          C128:  $29         Apple:  $021B 

Size! 

Byte 

Default: 

$09  for  BSB  9  font 

Saued?! 

Yes 

Description: 

Used  to. hold  the  card  height  in  pixels  of  the  current  font  in 
use. 

Note! 

Nane! 

curlndexTable 

Formerly! 

currentlndexTable 

Address! 

C64:  $2a          C128:  $2a         Apple:  $005E 
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Sizes  Word 

Default:  CoBuiodore:  $D218  for  BSU  9  font 

Apple:  $0C08  for  BSy  9  font 

Saved?:  Yes 

Description:      curlndexTable  points  to  the  table  of  sizes,  in  bytes,  of  each 
card  in  of  the  current  font.   On  the  Apple,  this  variable  only 
exists  in  the  back  ran  zero  page.   Aponcations  nust  switch 
zero  pages  before  accessing  it  directly. 


Hote: 

Nafoe: 

curnobx2 

Fomerly: 

Address: 

C64:  HA           C128:  $1302      Apple:  $D953 

Size: 

Byte 

Default: 

None 

Saued?: 

No 

Description: 

Imaoe  of  the  C64  Bobx2  register.   Used  for  C128  and  Apple 
soft  sprites.   Resides  in  back  ran. 

Note: 

Narne: 

curnoby2 

Foroerly: 

Address: 

C<4:  NA           C128:  $1301       Apple:  $0952 

Size: 

Byte 

Default: 

None 

Saued?: 

No 

Description: 

Inaqe  of  of  C64  Roby2  register.   Used  for  C128  and  Apple 
soft  sprites.  Resides  in  back  ran. 

Note: 

Nane: 

curPattern 

Foraerly: 

currentPattern 

Address: 

W4:  $22          C128:  $22         Apple:  $022c 

Size: 

yord 

Default: 

$0010 

Saved?: 

Yes 

Description: 

curPattern  points  to  the  first  byte  of  the  graphics  data  for  the 
current  pattern  in  use. 

Note: 

Each  pattern  is  1  byte  wide  and  8  bytes  bytes  high,  to  give  an 
8  by  8  bit  pattern. 

Apple:  The  location  of  patterns  pointed  t/  bu  cLrPattern  is  in 
back  raiB  and  should  not  be  accessed  directTyr^See  SetPattern 
and  GetPattern. 

Hai&e:  curRecord 
Formerly: 
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flddresss  C<4:  $849i        C128:  $8496       Apple:  $f<18 

Sizes  Byte 

Default:  $00 

Saued?:  No 

Descriptions  Holds  the  current  record  number  for  an  open  ULIR  file. 

Note:  Uhen  a  VLIR  file  is  opened,  using  OpenRecordFile,  curRecord  is 

set  to  0  if  there  is  at  least  1  record  in  the  file,  or  -1  if 
their  are  no  records. 


HaiBes 

Former lys 

fiddresss 

Size: 

Default: 

Saued?: 

Descriptions 


currentHode 

C64s  $2e  C128:  $2e         Apple:  $021C 

Byte 

$00 

Yes 

Holds  the  current  text  drawing  node.   Each  bit  is  a  flag  for  a 
drawing  style.   If  set,  that  style  is  actiue,  if  clear  it  is 
inactiue.   The  bit  usage  and  constants  for  naninuplating  these 
bits  are  as  follows. 

Bit      Style  Constant 

b7:  Underline  flag  SET  UNDERLINE  -  XIOOOOOOO 

b6:  Bold  flag  SETlOLO  «  XOIOOOOOO 

b5:  Reuerse  flag  SETlEUERSE  «  XOOIOOOOO 

b4s  Italics  flag  SETlTflLIC  =  MOOIOOOO 

b3s  Outline  flag  SEFOJITLINE  «  XOOOOIOOO 

b2s  Superscript  flag  SET"SUPERSCRIPT=J:00000100 

bis  Subscript  flag  SET  SUBSCRIPT  -  XOOOOOOIO 

bO:  Unused 

Clears  all  flags  (plain  text)    SETJLAINTEXT  =  WOOOOOOO 

Any  combination  of  flags  can  be  set  or  clear.   If  current 
node  is  plaintext,  all  flags  are  clear. 

Constants  that  can  be  used  within  text  strings  themselues  that 
affect  currentflode  ares 

UNDERLINEON,  UNDERLINEOFF,  REUERSEON,  REVERSEOFF,  BOLDON, 
ITflLICON,  OUTLINEON,  PLAINTEXT 


Note: 


Natte:  curSetVidth 

Formerly:  currentSetllidth 

Address:  C64:  $27  C128s  $27         Apples  $219 

Sizes  llord 

Defaults  Coonodores  $005c 
Apples  $0051 

Saued? s  Yes 

Descriptions  Holds  the  card  width  in  pixels  for  the  current  font 
Notes 


Na»es  curType 
Formerly: 


file:  printOutZ.agl,  page  8,  tine  Thu  flar  24  11:46:34  19B8 


Address:  C64:  $88ci        C128:  $88c6       Apple:  Nfl 

^Size:  Byte 
Default:  Disk  type  of  driue  8  for  Comnodore 

Saued?:  Ho 

Description:     Holds  the  current  disk  type.   This  ualge  is  copied  fron 
driueType  for  quicker  access  to  the  current  drive 
b7:  Set  if  the  disk  is  a  RAH  disk 
b6:  Set  if  using  disk  shadouing 

Only  one  of  bit  6  or  7  nay  be  set.  Other  constants  used  with 
curlype  are 

DRUjULL  "0     No  driue  present  at  this  device  address 
DRU  1541  >  1      Driue  type  Conmodore  1541 
DRU  1571  «  2     Drive  type  Connodore  1571 
DRVJ581  «  3     Drive  type  Comaodore  1581 


Note: 


Naoe:  curXposO     I  q  \^^f[f^ 
Forserly: 

Address:  C64:  NA  C128: /<1303/    Apple:  $0954 

Size:  16  bytes  ^  7 

Default:  None 

Saved?:  No 

Description:  The  current  X  positions  of  the  C128  and  Apple  soft  sprites. 
Resides  in  back  ran. 

Note: 


Nane: 
Formerly: 

curYposO    I  ^  \r^(£Ky>^ 

Address: 

C<4:  NA           C128:/il313y    Apple:  $0964 

Size: 
Default: 

None 

Saved?: 

No 

Description: 

The  current  Y  positions  for  the  C128  and  Apple  soft  sprites. 
Resides  in  back  ran. 

Note: 

Nai&e: 

devUnitTab 

Fornerly: 

Address: 

C64:  NA           C128:  NA          Apple:  $FAEF 

Size: 

4  Bytes 

Default: 

$60  in  each  byte 

Saved?: 

No 

Description: 

The  ProDos  unit  nuabers  of  the  four  possible  devices  are  kept 
here.  Used  for  conaunicating  with  the  device  drivers. 

Note: 


deuTabHi 
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Fornerly: 

fiddress: 

Cj4:  NA            C128:  NA 

Apple:  deuTabHi  -  $FA£7,  devTabLo  -  $FAEB 

Size! 

4  Bytes  each 

Default: 

deuTabHi  -  $D0  in  each  byte,  devTabLo  -  $00  in  each  byte 

Saved?: 

No  • 

Description: 

For  the  Apple,  these  are  the  high  and  lou  bytes  of  the  four 
possible  device  drivers. 

Note: 

Naoe: 

dirBUno 

Foraerly: 

Address: 

C64:  NA           C128:  NA          Apple:  $F620 

Size: 

Uord 

Default: 

$02 

Saved?: 

No 

Description: 

Block  number  of  the  key  block  of  the  directory  containing 
this  file's  entry. 

Note: 

Name: 

dirPtr 

Formerly: 

Address: 

C64:  NA           C128:  NA          Apple:  $F622 

Size: 

Uord 

Default: 

$00 

Saved?: 

No 

Description: 

Pointer  into  diskBlkBuf  for  this  file's  entry. 

Note: 

Haiae: 

diskBlkBuf 

Fornerly: 

Address: 

C64:  $8000        C128:  $8000       Apple:  $F659 

Size: 

Comaodore  -  256  bytes 
Apple  -  512  bytes 

Default: 

$00 

Saved?: 

No 

Description: 

Eeneral  disk  block  buffer.   Initialized  to  all  zeros. 

Note: 

Nai&e: 

doRestFlag 

Formerly: 

Address: 

C64:  NA           C128:  $lb54      Apple:  $DBld 

Size: 

Byte 
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Defaults 

Saued?s 

Description* 

Note! 


FALSE  »  0 
No 

Flag  needed  because  of  overlapping  soft  sprite  problens  on  C128 
and  Apple.  Set  to  TRUE  if  ue  see  a  sprite  that  needs  to  be 
redrawn  and  therefore  all  higher  numbered  sprites  need  to  be 
redrawn  as  well.   Resides  in  back  Raa. 


Naoie: 

Fornerly! 

Address: 

Size! 

Default! 

Saved?! 

Description! 


Note! 


driueType 

C64!  $848e        C128!  $848e       Apple:  $FAF3 
4  bytes. 

Set  to  type  of  drive  8  on  Connodore  or  drive  0  on  Apple. 
No 

There  are  4  bytes  at  location  driveType,  one  for  each  of  four 
possible  drives. 

For  CofWBodore,  each  byte  has  the  following  for»at! 

b7:  Set  if  drive  is  RAH  DISK 

h6'  Set  if  Shadowed  disk 

Only  1  of  bit  7  or  bit  6  aay  be  set 

Constants  and  values  used  for  drive  types  are 

Constant  Value  Type 

DRV  NULL  0         No  drive  present  at  this  device  address 

DRU'"1541  1         Drive  type  Commodore  1541 

DRri571  2         Drive  type  Commodore  1571 

DRVJ^Bl  3         Drive  type  Commodore  1581 

For  Apple,  the  only  differences  between  drive  types  is  whether 
the  drive  media  is  removable  (e.g.  floppy)  or  non-removable 
(e.g.  hard  drive).  The  bit  usage  is  as  follows: 

b7!  set  if  disk  medium  is  removable 

b6!  set  if  device  is  interruptable 

b5,4!  number  of  drives  on  the  device  (0-3) 

b3!  device  driver  supports  format 

b2!  device  driver  supports  write 

bl:  device  driver  supports  read 

bO:  device  driver  supports  status  call 


Th 
d 


his  bit  usage  conforms  to  the  information  ProDos  keeps  about 
isk  drives.   6E0S,  however,  only  makes  use  of  bits  7  and  3. 


Name!  drSizeLo,  drSizeHi 

Formerly!         driveSizeLo,  driveSizeHI 

Address:  C<4!  NA  C128!  NA 

Apple:  drSizelo  -  $  FAF7,  driveSizeHi  -  $FAFB 

Size:  4  Bytes  each 

Defaults  Hone 

Saved?!  Ho 

Descriptions     The  low  and  high  bytes  of  the  sizes  of  the  four  possible 
device  sizes. 


Note: 
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Kane: 

disi^^  j 

Forftcrlys 

Address^ 

C44:  ^^43a        Ci28:  $848a       Apple:  $F617 

Sizes 

Byte 

Default: 

TRUE  (§FF) 

Saved? 5 

No 

Description: 

Set  to  TRUE  or  FALSE  to  indicate  ubether  a  disi  is  currently 
open . 

Note* 

Name: 

DrflCurOliNa 

Forsier  lys 

Address! 

Cj4<  $841e        C128s  $841e       AddIc:  i?M7 

Size* 

Commodore  •  18  bvtes 
Apple  -  14  bytes 

Default: 

None 

Saved?: 

No 

Descr  iot  ion: 

This  is  the  disk  name  of  the  current  disk  in  drive  A. 

Illl^      1^     vllW                     II WUIW     wl      «IIW     WWIIWIlV     Ul^n      III    Wl    IVW  111 

Commodore  -  padded  uith  $A0 

Annlp  *-  nAHHpri  uitK  ADO 
nuu  ic      pauucu  m  i  vii  yvv 

Note: 

Na»e: 

DrBCurDkN« 

Fo(»erIy: 

Address: 

C44:  $8430        C128:  $8430       Apple:  $FAB7 

Commodore  "  18  butes 
Apple  -  14  bytes 

Default: 

None 

Saved?: 

No 

np<rr 1 inn ■ 

Thi<  1^  thp  di^k  nAfhP  flf  the  current  di^k  in  drive  B. 

11119     19    Vllu    U  1 9K    llQUtC    U 1     VllW    WUIIwllV    UI9I^     III    Ul  IVw  U* 

Commodore  -  padded  yith  $A0 
Anole  "  oadded  uith  SOO 

nupiw       VHUucu  w  1  VII 

Nntp: 

Nase: 

dataFileName 

Foraer ly: 

Address: 

C44:  $8442        C128:  $8442       Apple:  $02A4 

Size: 

Cnnnndore  *  17  bvtes 

bUIWiiWUUI  C  *• 

Apple  -  14  bytes 

Aof  All  If! 

uerau IV* 

Mil  AM 

none 

Saved?: 

Hp 

Description: 

This  is  the  naee  of  a  data  to  open.  The  name  is  passed  to  the 
parent  application  so  the  file  can  be  openned. 

Note: 
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Hane: 
)  For»erly: 
Address: 
Size: 

Default: 
Saved?: 
Description: 
Note: 


dataDiskNane 


C64:  $8453        C128:  $8453       Apple:  $02B4 

Com&odore  -  18  bytes 
Apple  -  li  bytes 

Hone 

Ho 

Holds  the  disk  nane  that  an  application's  data  file  is  on. 


Name: 

Foraerly: 

Address: 

Size: 

Default: 

Sayed?: 

Description: 


Naiie: 

Formerly: 

Address: 

Size: 

Default: 

Saved?: 

Description: 

Hote: 


dispBufferOn 
displayBufferOn 

C64:  $002f        C128:  $002f      Apple:  $021d 
byte 

(STJRJORE  I  STJRJACK)  «  $cO 
yes 

Routes  graphic  and  text  operations  to  either  the  foreground 
screen,  background  buffer,  or  both  simultaneously. 

b?: 
bi: 
b5: 


1  «  draw  to  foreground  screen  buffer 
1    draw  to  background  buffer 
1  «  limit  GetStnng  text  entry  to  foreground  screen. 
0  "  GetString  text  entry  will  use  b7,bi 
b4-bO:  reserved  for  future  usei  should  always  be  0 

Use  ST  HRJORE  (write  to  foreground)  and  STJRJACK  (write 
to  background)  to  access  these  bits. 

Note:  !(OOxxxxxxxx  is  an  undefined  state  and  will  result  in  sending 

most  graphic  operations  to  the  center  of  the  dtspaly  area. 


day 

C64:  $8518        C128:  $8518       Apple:  $F202 

Byte 

20 

Ho 

Holds  the  value  for  current  day. 


Name: 
Formerly: 
Address: 
Size: 

Default: 

Saved?: 

Descriptions 


dIgBoxRamBuf 


C64:  $851f        C128:  $851f       Apple:  $F381 

Commodore  -  417  Bytes 
Apple  -  64?  Bytes 

Hone 

Yes 

This  is  the  buffer  for  variables  that  are  saved  when  desk 
accessories  or  dialog  boxes  are  run. 
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Note: 


nai8C  * 

UI  ivcuava 

PflrikPr  1 11  * 
1  ui  ■ici  1  y " 

Address' 

C64:  $88bf       C128:  $88bf      Apple:  NA 

Size: 

4  bytes 

UCI uU 1 b  * 

None 

gdvcQ! * 

No 

liU 

Dp^cr lot  ion* 

UC9Wi   1  U  W  1  Uli 

One  bute  is  rss^rupd  for  each  disk  dr iup.  to  bp  us^d  hu  th^ 
the  disk  driver.  Each  driver  nay  use  it  differently. 

Note: 

nanic  * 

dbiriirkCniin^ 

UU  lb  1  IwKbUUIIW 

r oriBcr  ly • 

Address: 

C64:  $8515        C128:  $8515       Apple:  $0258 

Size: 

Byte 

Default: 

$00 

Saued?: 

No 

Description: 

Used  to  deteraine  uhen  an  icon  is  double  clicked  on.   Vhen  an 
icon  is  selected,  dblClickCount  is  loaded  with  a  value  of 
LLXLN^tuuni  i/V|.   OD it  1 iCRLounw  IS  vnen  oecreDcnieQ  eacn 
interrupt.   If  the  value  is  non-zero  uhen  the  icon  is  again 

ep1orfp<4     fhpn  fhp  Wmihlo  rlirk   flan  frOUl   i<  nAft<o<4  fn  fko 

service  routine  with  a  value  of  TRUE.  If  the  dblClickCount 
variable  is  zero  uhen  the  icon  is  clicked  on,  then  the  flag  is 
passed  uith  a  value  of  FALSE. 

Note: 

Nase: 

DrCCurDkNn 

Foriaerly: 

Address: 

C<4:  $88dc        C128:  $88dc       Apple:  $FAC7 

Size:  . 

CorDinodore  -  18  bytes 
AddIc  "  16  bvtes 

UCI au 1 w  * 

Nonp 

nunc 

wOVCU ! * 

No 

Dp^rr  \  nt.  \  nn  S 

Vw3Wi  iUblUII* 

Thi^  i^  the  disk  n^ftp  nf  thp  current  disk  in  driup  T 
Commodore  -  padded  uith  $A0 

Onnip  -  n^ddpd  uith  ^nO 

nUU  IC        uaUUCU    9  1  Wll   y  VV 

Note: 

Haoe: 

OrOCurOkHi 

Forwrlys 

Address: 

C64:  $88ee       C128:  $88ee      Apple:  $FflD7 

Size: 

Comodore  -  18  bytes 
Apple  -  U  bytes 

Default: 

None 

Saued?: 

No 

file:  printOutZ.agl,  page  14,  tiM  Thu  liar  24  11:46:34  1988 


Dp^rr intionS 

Thi^  1^  thp  fii^k  rififiP  nf  thp  nirrpnt  rfi<ir  in  ilrfiip  0 

11119    19    WIIC   UI9ft    lianC   Ul     VIIC   bUIICIIW    Ul9ft    III   Ul  IVC  w* 

Cottttodore  -  padded  with  $A0 
Aoole  ~  oadded  uith  SOO 

Nntp: 

Name: 

dirEfltryBuf 

FoFBGr ]y* 

Address: 

C<4s  $8400        C128S  $8400       Apoles  $FA59 

Size* 

CoQtnodore  ~  25^ 
Apple  -  39  bytes 

$00 

Saued?: 

Ho 

Descriptions 

Buffer  used  to  build  a  file's  directory  entry.   Initialized  to 

a}]  zpro^ 

all   fcCi  wjt 

Note: 

Name-* 

dir2Head 

ForaerlyJ 

Address: 

C<4:  $8900        C128:  $8900       Apple:  Nfl 

Sizes 

Conaodore  -  256  bytes 

Defaults 

None 

Saued?! 

No 

Descriptions 

This  is  the  2nd  directory  header  block  used  for  larger  capacity 
disli  driues  (e.g.  Coounodore  1571) 

Notes 

« 

Nanes 

dateCopy 

Fornerlys 

Addresss 

C64S  $C018        C128S  $C018       Apples  NA 

Sizes 

3  bytes 

Defaults 

Sane  as  variables  year,  lonth,  day 

wU vwu : 

No 

liU 

Dp^cr  i ot  ion! 

Thi<  i<  A  cfiQU  of  thff  ^u^tpfi  udr iahl#^  for  uesr    annth    AnA  Aau 

11119   19  a  biiwy  Ul    viiw  9y9irwM  vul  iauic9  i  wi    ywai  |  hiuiiwiI|  qiiu  uoyi 

Notes 

Nanes 

extclr 

Forterlys 

Addresss 

C64:  $0020        Ci28:  $0020      Apple:  NA 

Sizes 

Byte 

Defaults 

$FB 

Saued? s 

No 

Descriptions 

Holds  ualue  for  exterior  (border)  color. 

Notes 
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Nane: 

former ly! 

Address^ 

Sizes 

Defaults 

Saved?: 

Description-* 


fauitOata 

C64:  $84b6        C128:  $84b6       Apple:  $0227 

Byte 

$00 

Yes 

Holds  information  about  mouse  faults.  House  faults  occur  when 
the  mouse  attempts  to  aoue  outside  the  bounds  set  by  mouseLeft, 
aouseRight,  mouselop,  and  mouseBotton.   fl  fault  is  also 
signalled  when  the  mouse  is  outside  the  current  menu  area.  The 
bits  for  signalling  are  used  as  follouss 


Bit  Fault 

b/s  mouse  fault  up 

h6'  mouse  fault  down 

b5:  mouse  fault,  left 

b4:  mouse  fault  right 

b5:  menu  fault 


Constant  for  bit  access 

OFFTOP  BIT 
OFFBOTlOn  BIT 
OFFLEFT  BIT 
OFFRIGHT  BIT 
OFFtlENU  BIT 


Notes 


Names 
Formerly: 
Addresss 
Sizes 

Defaults 
Saued?s 
Descriptions 
Notes 


f ileHeader 


Cj4s  $8100        C128S  $8100      Apples  $F857 

Commodore  -  256  bytes 
Apple  -  512  bytes 

$00 

No 

Buffer  used  to  hold  the  header  block  for  a  6E0S  file. 


Names 

Formerlys 

Address: 

Sizes 

Defaults 

Saved?: 

Description: 

Note: 


f ileSize 

C64:  $8499        C128:  $8499       Apple:  $F<1B 

Uord 

None 

No 

This  is  the  current  size  (in  blocks)  of  a  file.  It  is  pulled 
in  from  and  written  to  the  file's  directory  entry. 


Name: 

Formerlys 

Addresss 

Sizes 

Defaults 

Saved? s 

Descriptions 


fileTrScTab 

C64s  $8300       C128S  $8300      Apples  NA 

25<  Bytes 

$00 

No 

For  Commodore,  it  is  the  buffer  used  to  hold  the  track  and 
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Hote: 


sector  chain  for  a  file  of  ■axinue  size  of  32258  bytes. 


Nai&e: 

Fomerlys 

ftddresss 

Size* 

Default: 

Saved?: 

Description: 

Notes 


C128:  $8498       Apple:  $F£1A 


fileyritten 

C£4:  $8498 
Byte 
None 
No 

Flag  indicating  if  a  if  the  currently  open  file  has  been  uritten 
to  since  the  last  update  of  its  index  table  and  the  Bfttl. 


Nai&e: 

Foraerlys 

Address: 

Size: 

Default: 

Saued?: 

Description: 

Note: 


firstBoot 

C64:  $88c5        C128:  $88c5       Apple:  $0281 
Byte 

See  below 
Ho 

This  flag  is  changed  fron  0  to  $FF  uhen  the  desklop  coaes  up 
after  booting. 


f^ntOata 
saueFontTab 

rrl850C       C128:  $850c  Appl 
9  bytes 
None 
No 

Description:     Buffer  for  sauing  the  user  active  font  table  uhen  going  into 
nenus. 

Note: 


"JntTable  ^ 
cardDat| 

4:  $26  C128:  $26 

8  bytes 

Default  font  information 
Yes 


Appl 


<™2 


Saued?: 

Description:     fontTable  is  a  label  for  the  beginning  of  variables  for  the 
current  font  in  use.  These  variables  are  baselineOffset, 
curSetllidth.  curHeight,  curlndexTable,  and  cardOataPntr. 
For  more  inroraation,  see  docusentation  on  these  variables. 


Note: 
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Nane: 

grcntrll 

Foraerlys 

Address: 

C64:  $0011        C128:  $0011       Apple:  NA 

Size: 

Byte 

Default: 

$55 

Saued?: 

Ho 

Hacr p 1 nf 1 nn  S 
UC^Ci  ip  V  lUit* 

ijiapiiius  buiiwiui  icijoicr  ffi|  ic  bpu  raster/ ctii/oiut/ucn/ngCL/y 
scroll  bits  defined  for  use  with  above  reg. 
st^eca    «  S40 

<f  KmM      s  470 

St  Jen    «  510 
st  25rou  «  508 

Note: 

Nane: 

grcntrl2 

Formerly: 

Address: 

C64:  $0016        C128:  $0016       Apple:  NA 

Size: 

Byte 

Default: 

$AA 

Saued?: 

no 

Description: 

graphics  control  register  12,  ie:  RES/flCfl/CSEL/x  scroll  bits 

t  nt%A    91%^    Ilea   iii^K  AnAiia 

QcrineQ  ror  use  uicn  aoove  reg. 
St.BCBI     =  510 

Note: 

Name: 

grirq 

Formerly: 

Address: 

C64:  $0019        C12B:  $001?      Apple:  NA 

Size: 

Byte 

Default: 

$42  . 

jovcu : * 

Nn 
no 

Hpcrr {nt inn* 

nrdohic^  chin  intprriini!  fpti\^tpr 

ilU  wc* 

Nane: 

grirqen 

ForBerly: 

Address: 

C64>  $d01a       C128:  $d01a      Apple:  NA 

Size: 

Byte 

Default: 

$24 

Saved?: 

No 

Description: 

graphics  chip  interrupt  enable  register 

bit  to  enable  raster  interrupt  in  grirqen  is  bit  0 

St  rasen  »  $01 

Note: 
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Name: 

Fornierlys 

Address: 

Size: 

Default: 

Saued?: 

Description: 

Note: 


grnenptr 

C64:  $d018^      C128:  $d018       Apple:  NA 
Byte 

No 

graphics  nenory  pointer  Vni3-UniO|CB13-CBll.  ie  video  satrix 
and  character  base. 


Name: 

Fornerly: 

Address: 

Size: 

Default: 

Saved?: 

Description: 

Note: 


hour 

C64:  $8519        C128:  $8519       Apple:  $F203 

Byte 

12 

Ho 

Variable  for  hour 


Name: 

Formerly: 

Address: 

Size: 

Default: 

Saved?: 

Description: 


C128:  $84b5      Apple:  $0226 


iconSelFlag 

C64:  $84b5 
Byte 
$00 
Yes 

This  RAH  variable  contains  flag  bits  in  b7  and  b6  to  specify 
how  the  systes  should  indicate  icon  selection  to  the  user,  if 
no  bits  are  set,  then  the  systett  toes  nothing  to  indicate  icon 
selection,  and  the  service  routine  is  sinply  called. 
The  possible  flags  are: 

ST  FLASH  «  $80  \  flash  the  icon 
STiINVERT  «  $40  ;  invert  the  selected  icon 

If  ST  FLASH  is  set,  the  ST  INVERT  flag  is  ignored  and  the  icon 
flashes  but  is  not  inverted  when  the  prograttner's  routine  is 
called.  If  ST  INVERT  is  set,  and  STJLASR  is  CLEAR,  then  the 
icon  uill  be  Inverted  uhen  the  prograiMier's  routine  is  called. 


Note: 


Name: 

Formerly: 

Address: 

Size: 

Default: 

Saved?: 

Description: 


indexBlkno 


Apple:  $F624 


C64:  NA  C128:  NA 

Uord 
$00 
No 

Block  number  of  the  VLIR  index  table  (ProDos  master  index 
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block). 

Note« 

Name: 

inputData 

FortterlyJ 

Address: 

C64:  $8506        C128:  $8506       Apple:  $0247 

Size: 

4  bytes 

Default: 

None 

Saued?: 

No 

Description: 

This  is  where  input  driuers  pass  deuice  specific  inforaation  to 
applications  that  want  it. 

Note: 

Nane: 

inputDeuNarse 

forwerly: 

Address: 

C64:  $88cb        C128:  $88cb      Apple:  $08CC 

Size: 

Comnodore  -  17  bytes 
Apple  -  16  Bytes 

Default: 

None 

Saued?: 

No 

Description: 

String  that  holds  the  name  of  the  current  input  deuice. 
e.g.  Conn  nOUSE  for  coflinodore  mouse. 

Note: 

Name: 

inputVector 

Foriaerly: 

Address: 

C64:  $84a5       C128:  $84a5      Apple<  $020A 

Size: 

Uord 

Default: 

$00 

Saued?: 

No 

Description: 

Pointer  to  routine  to  call  on  input  deuice  change. 

Note: 

Haine: 

intfiotVector 

Forfterly: 

interruptBottoaVector 

Address: 

C64:  $849f        C128:  $849f       Apple:  $0204 

Size: 

Hord 

Default: 

$00 

Saued?: 

No 

Description: 

Vector  to  routine  to  call  after  the  operating  systea  interrupt 
code  has  run.  This  allows  applications  to  haue  interrupt  leuel 
routines. 

Hote: 
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Watae''  intlopVector 
Fornerlys  interruptTopVector 


Address! 

Ci4:  $849d        C128:  $849d      Apple:  ^0202 

Size: 

Uord 

uciau 1 V  * 

Y  V  V 

wQVCU : * 

No 

Dp^cr  iotion* 

Vector  to  routine  to  call  before  operating  systen  interrupt 
code  is  run.   It  allous  applications  to  interrupt  leuel 
routines. 

llU  bC* 

Name: 

intSource 

Foraerly! 

interruptSource 

Address: 

C64:  NA           C128:  NA          Apple:  $02C6 

Rut? 

Default: 

None 

Saued?: 

No 

Description: 

Byte  to  indicate  where  interrupts  are  coning  fron  on  the  Apple. 

$oO  indicates  nouse  card 

^40  indicates  interrupt  nanagenent  card 

$00  indicates  software  interrupts 

Note: 

Nane: 

interleaue 

Forierly: 

nuui  ww9* 

C64:  i848c        C128:  $848c       Aoole:  NA 

Size: 

Byte 

Defaults 

$08 

Saued?: 

No 

Description: 

Vartabje  used  by  BIkAlloc  routine  as  the  desired  interleaue  uhen 

ocicwwiitM  1 1  cc  uiuwiks  1  III  a  ui3i^  Liiaiii* 

liU  * 

Nane: 

inuertBuffer 

Fornerly: 

CM:  NA             ri7A:  ^Irpd        Annlp:  Nfl 
but"  iin                wi4D*  yiucu         nupic*  nn 

Size: 

80  Bytes 

Default: 

None 

Saued?: 

No 

Description: 

Buffer  area  used  to  speed  up  the  80  colunn  InuertLine  routine. 
Resides  in  back  Ran. 

Hote: 

Naoie: 

irquec 

Fornerly: 
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Address: 

C64:  $0314        C128:  $514        Apple:  HA 

Size: 

Uord 

Default: 

$?5fd 

Saued?: 

No 

Description: 

irq  uector. 

Hote: 

Haiae: 

isGEOS 

Fornerly: 

Address: 

C64:  $848b        C128:  $849b       Apple:  HA 

Size: 

Byte 

Default: 

Disk  dependent 

Saued?: 

No 

Description: 

Flag  to  indicate  whether  the  current  disk  is  a  GEOS  disk. 

Note: 

Haine: 

keyData 

Fornerly: 

Address: 

C64:  $8504        C128:  $8504      Apple:  $0245 

Size: 

Byte 

Default: 

$00 

Saued?: 

No 

Description: 

Holds  the  ASCII  ualue  of  the  current  last  key  that  uas  pressed. 
Used  by  keyboard  seruice  routines. 

Note: 

Nane: 

keyUector 

Foraerly: 

Address: 

C64:  $84a5       C128:  $84a5      Apple:  $0208 

Size: 

Uord 

Default: 

Comnodore  -  $26A1 
Apple  -  $416D 

Saued?: 

Yes 

Description: 

Uector  to  routine  to  call  on  keypress 

Note: 

Natae: 

leftHargin 

Fornerly: 

nUUl * 

C'64:  $0055        C128:  $0055      Apple:  $0220 

Size: 

yord 

Default: 

$00 

Saued?: 

Yes 
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Description: 

Leftmost  point  for  writing  characters.  Doing  a  carriage 
return  uiil  return  to  this  point. 

Note: 

Nane: 

BachineType 

Foraerly: 

Address: 

C64:  NA           C128:  NA          Apple:  $02C4 

Size: 

Byte 

Default: 

None 

Saved?: 

No 

Description: 

Type  of  Apple  nachine.   Values  are: 
^00:  He 

$80:  lie  or  something  else 

Note: 

Nane: 

eaxflouseSpeed 

Fornerly: 

saxifiuiDnouseSpeed 

(Iddress: 

C64:  $8$01        C128:  $8501       Apple:  $027D 

Size: 

Byte 

Default: 

$7f  (127) 

Saved?: 

No 

Description: 

llaxiiDUtt  speed  for  nouse  cursor. 

Note: 

Nai&e: 

BcnclrO,  BCDctrl 

Formerly: 

Address: 

C64:  $d025,  $d026 
C128:  $d025,  $d026 
Apple:  NA 

Size: 

1  Byte  each 

Default: 

None 

Saved?: 

No 

Description: 

These  are  the  variables  for  Bulti-color  node  colors  0 
and  1  respectively  on  the  Connodore. 

Note: 

Hane: 

nenuNuttber 

Foraerly: 

Address: 

C64:  $84b7        C128:  $84b7       Apple:  $0228 

Size: 

Bvte 

Default: 

$00 

Saved?: 

No 

Description: 

Nunber  of  currently  uorking  aenu 
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Notes 


Ha»es 

ttinflouseSpeed 

foraerlys 

niniKunflouseSpeed 

flddress-' 

Ci4!  $8502        C128!  $8502      Apple:  $027E 

Size! 

Byte 

Default! 

He  (30) 

OdUCU! * 

Nn 

no 

np<rr intionS 

nininuii  ^nppH  fnr  nnii<sP  nircnr 

Note! 

Name! 

ninutes 

Foroerly! 

Address! 

C«!  $851a        C128!  $85Ia      Apple:  $F204 

Size! 

Byte 

Default! 

$00 

Saued?! 

No 

Description! 

Variable  for  ainutes  for  tine  of  day  clock. 

Note! 

llaiUC  * 

(nnhOrlr    nnhlrlr    nnhJrlr    nnK^rlr    itnhArlr-  mnK^rlr 

0)ob6clr,  Bob7clr 

Foriaerlyi 

Address! 

C64i  $d027  -  $d02e 

Apple:  NA 

Size! 

1  Byte  each 

ucrdu 1 w  * 

none 

Sdupd?! 

Uwvcu : * 

No 

liU 

uescr ipwion* 

inese  are  ine  colors  or  vne  o  oojecws  ^spriiesj  on  LoiD&oooret 

Note! 

Nai&e! 

nobOxpos,  nobOypos,  noblxpos,  noblypos,       Aob7xpos,  Bob7ypos 

Fornerly! 

Address! 

C64:  $0000  -  $DOOF 

Apple:  Nfl~  r/t(A 

W  i  bC  * 

1  Rutp  pArh 
*  uy  vc  cavil 

Default! 

None 

Saved?: 

Ho 

Description! 

These  are  the  x  any  y  positions  of  sprites  10  to  17 

respectively. 

Note: 

ttobbakcQl 
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For»erly: 


Address: 

C64:  $d01f        C128:  $d01f       Apple:  NA 

Size: 

Byte 

Default: 

None 

Saued?: 

No 

Description: 

sprite  to  baciiground  collision  register  for  Connodore. 

Note: 

ndiDC  * 

pArnor In • 

r ur mci  ly • 

nuui  * 

Ci4:  idol$        C128:  id015       Apple:  $0818 

Size: 

Byte 

Default: 

$01 

Saued?: 

No 

Description: 

sprite  enable  bits 

Note: 

NafDe: 

Biobncm 

r  ornpr 1u* 

Address: 

n  M  v«  1  www 

C64:  $d01c        C128:  $d01c       Apple:  NA 

Size: 

Byte 

Default: 

$00 

Saued?: 

No 

Description: 

sprite  nulti-color  node  select 

Note: 

Nane: 

Bobnobcol 

Forn^r 1u* 

Address: 

C64:  $d01e        C128:  $d01e      Apple:  NA 

Size: 

Byte 

Default: 

§00 

Saued?: 

No 

Description: 

object  to  object  collision  register 

Note: 

Nai&e: 

nnhor lor 

Fornerly: 

Address: 

C64:  $d01b        C128S  $d01b       Apple:  HA 

Size: 

Byte 

Default: 

$00 

Saued?: 

No 
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Description: 

object  to  background  priority 

Note: 

Naitte: 

Bobx2,  BobyZ 

Forierly: 

Address: 

C64:  $d01d,  d017  respectively 
LlZo*  $dOId,  dOu  respectively 
Apple:  $0819,  $081A 

Size: 

1  Byte  each 

Default: 

$00 

Saved?: 

No 

Description: 

Double  object  size  in  x  and  y  respectively 

Note: 

Haoe: 

Bonth 

Foraerly: 

Address: 

Ci4:  $8517        C128:  $8517       Apple:  $F201 

Size: 

Byte 

Default: 

$09 

Saued?: 

No 

Description: 

Holds  Bonth  for  time  of  day  clock 

Note: 

Name: 

BouseAccel 

Foraerly: 

BOuseAcceleration 

Address: 

C64:  $8503        C128:  $8503 

Size: 

Byte 

Default: 

$75  (127) 

Saved?: 

No 

Description: 

Acceleration  of  aouse  cursor 

Note: 

Nane:  BOuseBottoa 
Foraerly: 

Address:  C64:  $84b9        C128:  $84b9       Apple:  $0058 

Size:  Byte 

Default:  C64  -  199 

Apple  -  191 

Saved?:  Yes 

Description:     Bottoa  Bost  position  for  aouse  cursor.  Noraally  set  to  bottoa 
of  the  screen. 

Note: 
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BOUseFaultUec 

Foroerlys 

BOUseFaultUector 

Address! 

C64:  ^84a7        0128:  $84a7       Apple:  $020C 

Size! 

Uord 

Default! 

Systen  handling  routine 

Saved?! 

Yes 

Description! 

Vector  to  routine  to  call  uhen  laouse  goes  outside  region 
defined  for  nouse  position  or  when  louse  goes  off  of  a  aenu. 

Note! 

Naine! 

wouseLeft 

.ForiBerly! 

Address! 

C64!  $84ba        C128i  $84ba       Apple:  $0059 

Size! 

Vord 

Default! 

$00 

jdvCU : * 

Yes 

Descr iotion! 

Left  Bost  position  for  Bouse 

Note! 

Name! 

nouseOn 

Foroerly! 

Address! 

C64!  $30          C128:  $30         Apple:  $0050 

Size! 

Byte 

Default: 

$E0 

Saued?! 

Yes 

Description! 

Flag  indicating  that  the  Bouse  is  Bode  is  on.   Bit  usage  and 
constants  for  accessing  theB  are  as  follows 

Bit      flode  Constant 

b?!      Bouse  on  if  set           SET  HOUSEOH  »  UOOOOOOO 
b6!       nenus  on  if  set           SErriENUON  »  XOIOOOOOO 
b5!       icons  on  if  set           SETlICONSOH  «  ZOOIOOOOO 
b4  "  bO  not  used 

Note! 

Nane! 

BOUsePicData 

FortDerly! 

Address! 

W4:  $84cl        C128!  $84cl       Apple:  NA 

Size! 

64  bytes 

Default! 

BOUse  pointer  picture 

Saued?! 

No 

Description! 

64  byte  array  for  the  Bouse  sprite  picture  on  CoBBodore 

Note: 

Naae: 


BouseRight 
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ForaerlyJ 

ftddressJ 

C64:  $84bc       C128:  $84bc      Apple«  $005B 

Size* 

Uord 

Default: 

C<4  -  319 

ClZo  -  65/ 
Apple  -  559 

2)auedf  • 

les 

Description! 

Right  Bost  position  for  Bouse. 

note- 

Nantes 

BiouseSaue 

fornerlys 

Address'' 

Ci4s  NA           C128S  $1655       Apples  $EE53 

Sizes 

24  Bytes 

Defaults 

None 

Saued?s 

No 

Descriptions 

Screen  data  for  what  is  beneath  nouse  soft  sprite.   Resides  in 
Dacx  Kan. 

notes 

Names 

BouseTop 

Foroerlys 

flddresss 

C64S  $84b8        C128S  $84b8      Apples  $0057 

Sizes 

Byte 

Defaults 

$00 

SauedfS 

Yes 

Descriptions 

Top  Bost  position  for  aouse 

Notes 

Nases 

BouseUector 

Foraerlys 

flddresss 

C64:  $84al        C128s  $84al       Apples  $020i 

Sizes 

Uord 

Defaults 

Systen  routine  for  icons,  nenus,  etc. 

Saued?s 

Yes 

Descriptions 

Routine  to  call  on  a  Bouse  key  press 

Note: 

Nane* 

BOUseXPos 

Foraerlys 

BOUseXPosition 

Address: 

Ci4s  $3a          C128:  $5a         Apples  $0241 

Size: 

Uord 
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Default: 

None 

Saved?: 

No 

Description: 

House  X  position 

Note: 

Name: 

■ouseYPos 

Foraerly: 

RouseYPosition 

Address: 

C64:  $3c          C128:  $3c         Apple:  $0243 

Size: 

Byte  —  ' 

Default: 

None 

Saved?: 

No 

Description: 

House  Y  position 

Note: 

Nane: 

BOUseXOffset 

Formerly: 

Address: 

C64:  NA           C128:  NA          Apple:  $0229 

Size: 

yord 

Default: 

$00 

Saved?: 

No 

Description: 

Offset  froB  nouseXPos  to  draw  BOuse  sprite.   Froa  -$8000 
to  $7fff 

Note: 

Nafie: 

BouseYOffset 

Foraerly: 

Address: 

C64:  $             C128:  $            Apple:  $022B 

Size: 

Byte 

Default: 

$00 

Saved?: 

No 

Description: 

Offset  froB  BouseYPos  to  draw  the  souse  sprite.  FroB  -128  to 
127 

Note: 

Nane: 

Bsbxpos 

Fornerly: 

Address: 

C64S  $d010       C12B:  $d010      Apple:  NA 

Size: 

Byte 

^^.y  Default: 
Saved?: 
Description: 
Note: 
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Naoe: 

BsePicPtr 

for»erIy: 

BousePicture 

Address: 

C<4:  $31          C12B:  $31         Apple:  HA 

Size: 

Uord 

Default: 

$84cl 

Saued?: 

Yes 

Description: 

pointer  to  the  nouse  graphics  data 

Note: 

Naise: 

Formerly: 

Address: 

Size: 

Default: 

Saved?: 

Description: 


Note: 


C128:  $c010       Apple:  $EOOD 


nationality. 

C64:  $c010 
Byte 

0  -  American 
No 


Byte  to  hold  nationality  of  Kernal.   Values  are: 

0  American 

1  German 

2  French  (France  S  Belqiun) 

3  Dutch 

4  Italian 

5  Swiss  (Switzerland) 

6  Spanish 

7  Portugese 

8  Finnish  (Finland) 

9  UK 

0  Norwegian  (Norway) 

11  Danish  (Denmark) 

12  for  Swedish 


Name: 

nmiuec 

Formerly: 

Address: 

Ci4:  $0318        C128:  $318        Apple:  NA 

Size: 

Uord 

Default: 

$90c9 

Saued?: 

Ho 

Description: 

NUI  vector 

Note: 

Name: 

noEraseSprites 

Formerly: 

Address: 

C64:  HA           C128:  HA          Apple:  $0240 

Size: 

Byte 

Default: 

FALSE  »  $00 

Saued?: 

Ho 

Description: 

Flag  to  stop  routine  TempHideftouse  from  erasing  sprites  12  - 
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17.  Set  bit  V  (set  to  $80)  to  signal  not  to  erase  sprites. 


Note: 


Nane: 

Forwerly: 

Address: 

Size: 

Default: 

Saued?: 

Description: 

Note: 


nunDriues 

C64:  $848d  C128:  $848d  Apple: '$F60E 
Byte 

Drive  dependent 
Ho 

Set  to  nunber  of  drives  on  the  syste« 


Name: 

Formerly: 
Address: 

Size: 

Default: 

Saued?: 

Description: 

Note: 


objOPointer,  objlPointer,  obj2Pointer,  obj3Pointer,  obj4Pointer, 
objSPointer,  obj6Pointer,  obj7Pointer 


Ci4:  $8ff8  -  $8fff 
C128:  $8ff8  -  $8fff 
Apple:  NA 

1  Byte  each 

objOPointer  is  set  to  louse  cursor  picture 
Ho 

Pointers  to  the  picture  data  for  sprites 


Hafse: 

Formerly: 

Address: 

Size: 

Default: 

Saued?: 

Description: 


Hote: 
^^^^  Hame: 


C128:  HA  Apple:  $027C 


offFlag 

C64:  NA 
Byte 

FALSE  »  $00 
Ho 

Flag  telling  uhether  the  louse  needs  to  be  redraun.  It  is  used 
as  follows: 

Value 

$80      iouse  is  erased;  do  not  redraw  it  during  interrupt 
aouse  is  erased;  OK  to  redrau  it  next  interrupt 


$40 
$00 


nornal:  iouse  is  displayed.  (Rust  be  erased  before 
draun  at  a  new  position.) 


$ff      (negatiue/set  to  TRUE  anytiae  TettpHidedouse  is  called) 

otherPressVec 
Fomerly:  otherPressVector 

Address:  C64:  $84a7        C128:  $e4a7      Apple:  $020E 

Size:  Uord 
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Default t 

$00 

Saved? s 

Yes 

Descriptions 

Vector  to  routine  that  is  called  uhen  the  louse  button  is 
pressed  and  it  is  not  on  either  a  aenu  or  an  icon. 

Note: 

Hane: 

pressFlag 

Forwrlys 

Address! 

C64s  $39          C128!  $39         Apple!  $08FE 

Size! 

Byte 

Default: 

$00 

Saved?! 

No 

Descriptions 

Flag  to  indicate  that  a  neu  key  has  been  pressed.  Bit  usage! 

b7:  key  data  is  neu  ^ 
b<!  disk  data  is  neu      f  ■  - 
b5!  Bouse  data  is  neu 

Note! 

Naoe! 

PrntFilenaiae 

Forierly! 

Address! 

C64!  $8465        C128!  $8465       Apples  $08AC 

Size? 

Cownodore  -  17  bytes 

Default! 

None 

Saved?.! 

« 

No 

Description! 

Name  of  the  current  printer  driver 

Note! 
• 

Naie! 

PrntOiskNane 

Fornerly! 

Address! 

C64S  $847i        C128S  $8476      Apples  NA 

Size! 

Conmodore  -  18  bytes 

Default! 

None 

Saved?! 

No 

Description! 

Disk  na»e  that  current  printer  driver  is  on 

Note! 

Nane! 

ranBase 

Formerly! 

Addr^^s! 

nuui 

C64s  i88c7        C128!  $88c7      flpples  NA 

Size! 

4  bytes 

Default! 

None 

Saved?! 

No 
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Description: 

RAH  bank  for  each  disk  drive  to  use  if  the  driue  type  is  either 
»  RAH  Di^k  or  Shadoued  Driue 

note* 

Name: 

ranExpSize 

Foraerly: 

Address: 

Ci4:  $88c3        C128:  $88c3       Apple:  NA 

Size: 

Byte 

Default: 

RAH  driue  dependent 

saueo: • 

no 

uescr ipt lon* 

Dyvc  lor  nuoiuci  or  laii  uoiik?  avaiiauic  iii  nan  CApaii^ioii  uiiiv* 

Naoe: 

randon 

Foraerly: 

Address: 

Ci4:  $850a        C128:  $850a       Apple:  $024C 

Size: 

Vord 

Default: 

None 

oauedf • 

no 

vC3l#l  1  U  W  1  Ull  * 

UArifihlp  incrpfipntpd  PAch  intprruot  to  o^n^ratp  a  rArtAnin  niifshpr 

vol   lOUiw    lllwi  wWCII  WwU   wQwII     III  vwl  1  UU  w    « U    UwllCI  BWC   O    iOIIUUH  IIUIhUCI 

note' 

Name: 

rasreg 

Foraerly: 

Address: 

C64:  $d012       C128:  $d012      Apple:  NA 

Size: 

Byte 

Default: 

None 

^avcu: * 

Nn 
no 

uescr ipx ion* 

raster  register 

Naae: 

RecouerVector 

Foraerly: 

Address: 

C64:  $84bl       C128:  $84bl      Apple:  $0216 

Size: 

Hord 

Default: 

Points  to  RecouerRectangle  routine 

Saued?: 

Yes 

Description: 

Pointer  to  routine  that  is  called  to  recouer  the  background 
behind  nenus  and  dialogue  boxes.  Noraally  this  routine  is 
RecouerRectangle,  but  the  user  can  supply  his  oun  routine. 

Note: 

Name:  returnAddress 
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Forierlys 


Address: 

C64:  $3d       '   C128:  $3d         Apple:  $0064 

Size: 

Vord  • 

Default: 

None 

Saved?: 

Ho 

Description: 

Address  to  return  to  from  in-line  call 

Note: 

iiaiuc  * 

Ttin)ll\n<(\      rDAVnnel      paiiVnne?      »csaVam«7  •M^V»j%«it 

reqAposy,  reqAposi,  reqAposz,  reqApos^,  reqXpo54, 
reqXposS,  reqXpos6,  reqXpos? 

Formerly: 

Address: 

C64:  NA           C128:  NA          Apple:  See  below 

Size: 

Tuo  Bytes  each 

Default: 

None 

Saved?: 

No 

Description: 

These  variables  correspond  to  the  Coaaodore  VIC  chip  registers 
for  sprite  X  positions.   They  reside  at: 
reoXna^O  ^0800 
reqXposl  ^0802 
reqXpos2  i0804 

1 cuAuu^y  ovuvo 

reqXpos4  f0808 

1  w«^opu9y  9vUVCl 

reqXpos6  i080c 

1 CUApUPr  yVOVC 

Note: 

Name: 

rightHargin 

Foriierly: 

Address: 

C64:  $37          C128:  $37         Apple:  $0222 

Size: 

Hord 

Default: 

C64  -  31? 
C128  -  639 
Apple  -  559 

waveor  * 

Yp< 

ICS 

i/csur  ipw ion* 

Thp  rinhtnn^t  Doint  for  uritino  characters.    If  an  Attpmnt  i< 
Bade  to  urite  past  riqhtHargin,  the  routine  pointed  to  by 

Qf r innrAiilfUpr  i<  PftliPd. 
3 wi  inur du 1 bVCw  i^  waiicut 

noic* 

Naoe: 

saveFontTab 

rnrnpr luS 
r  ui  nci  1  y " 

C64:  $850c        C128:  ^A^Oc       Aoole:  $024E 

Size: 

Cowodore  -  9  bytes 
Apple  -  10  Bytes 

Default: 

None 

Saved?: 

Ho 

Description: 

Uhen  a  aenu  is  selected,  the  users  active  font  table  is  saved 
in  this  buffer. 
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Note: 

Nane: 

forwrlys 

Address! 

Size« 

Defaults 

Saved? 8 

Description' 

Note: 


sauedaobyZ 

C64:  $88bb        C128:  $88bb       Apple;  NA 

Byte 

None 

Yes 

Saued  ualue  of  Boby2  for  context  sauing  done  when  dialogue  boxes 
and  desli  accessories  run.  Because  this  was  left  out  of  the 
original  6E0S  saue  code,  it  uas  put  here  so  it  remains 
conpatible  with  desk  accessories,  etc.  that  use  the  size  of 
TOTJRAtlJAVED  for  how  what  gets  saued. 


Nai&e: 

foraerlys 

Address*' 

Size: 

Default: 

Saued?: 

Description: 

Note: 


scrSOcolors 


C64:  NA 
Byte 
None 
No 


C128:  $88bd      Apple:  NA 


Screen  colors  for  80  coluan  node  on  the  C128.  It  is  a  copy  of 
reg  26  in  the  UDC.  ^ 


Naiae: 

Foroerly: 

Address: 

Size: 

Default: 

Saved?: 

Description: 

Note: 


scrBOpolar 


C128:  $88bc      Apple:  NA 


C64:  NA 
Byte 

None  ?? 
No 

Copy  of  reg  24  in  the  UDC  for  the  C128 


Naae: 

Fomerly: 

Address: 

Size: 

Default: 

Saued?: 

Description: 

Note: 


screencolors 

C64:  $851e  C128:  $851e  Apple:  NA 
Byte 

$BF  (1?1) 
No 

Default  screen  colors 


Naae: 


seconds 
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For»erly: 


Address: 

Ci4:  $851b        C128:  $851b       Apple'  $F205 

Size: 

Byte 

Default: 

$00 

Saued?: 

Ho 

Description: 

Seconds  variable  for  the  tine  of  day  clock. 

Note: 

Nane: 

selectionFlash 

Forwerly: 

Address: 

C64:  $84b3        C128:  $84b3       Apple:  $0224 

Size: 

Bute 

Default: 

SLECTIONJELAY  «  $0A  (10) 

Saved?: 

Yes 

Description: 

Variable  for  the  speed  at  uhich  nenu  iteas  and  icons  are 
flashed. 

Note: 

Kane: 

shiftBuf 

Foraerly: 

Address: 

C64:  NA            C128:  $lb45       Apple:  $0070 

Size: 

7  bytes 

Default: 

None 

Saued?: 

No 

Description: 

Buffer  for  shifting/doubling  sprites.  Located  in  back  Raa. 

Note: 

Nar&e: 

shiftOutBuf 

Formerly: 

Address: 

C64:  NA           C128:  $lb4c      Apple:  $0078 

Size: 

7  Bytes 

Default: 

None 

Saued?: 

No 

Description: 

Buffer  for  shifting/doubling/oring  sprites.  Located  in  back 
Raa. 

Note: 

HaiBe: 

sizeFlags 

Foraerly: 

Address: 

C64:  NA           C128:  $lb53       Apple:  $DB1C 

Size: 

Byte 

Default: 

None 
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Sdued?s 
Descriptions 

Note* 


No 

height  of  sprite  |  9-pixel  flag  this  is  grabbed  froi  the  64th 
byte  of  the  sprite  definition.  The  high  bit  is  set  if  the 
sprite  is  only  9  pixels  wide.  The  rest  of  the  byte  is  a 
count  of  scan  lines. 


Nanes 

Foraerly* 

Address*' 

Size: 

Default! 

Saved?! 

Description! 

Note! 


softZeros 

C64!  Nft 
192  Bytes 
None 
No 


C128!  $lb6d      Apple!  $DOEO 


Buffer  used  for  putting  sprite  bitmaps  uo  on  screen  without 
disturbing  background.  Resides  in  back  RaM. 


NaiDe! 

fori&erly! 

Address! 

Size! 

Default! 

Saued?! 

Description! 

Note!  • 


softOnes 

C64!  NA 
192  Bytes 
None 
No 


C128!  $lc2d      Apple!  $D0OO 


Buffer  used  for  putting  sprite  bitnaps  uo  on 
disturbing  background.   Resides  in  back  Ran. 


on  screen  without 


Naae! 

Foraerly! 
Address! 

Size! 
Default! 
Saued?! 
Description! 

Note! 


sprOpic,  sprlpic,  spr2pic,  spr3pic,  spr4pic,  spr5pic, 
spr6pic,  sprZpic 


C64!  $8a00  -  8bc0  respectively 
C128!  ^8a00  -  8bc0  respectively 
Apple!  NA 

64  bytes  each 

sprOpic  is  used  for  souse  picture 
No 

This  is  uhere  the  graphics  data  for  sprites  0  -  7  are  kept  on 
the  C64. 


Name! 

Foroerly! 

Address! 

Size: 

Default! 


ssprlback,  sspr2back,  sspr3back,  sspr4back,  ssprSback, 
sspr6back,  sspr7back 


C64:  NA 


C128:  See  belou 


Apple:  $5600 


Commodore  -  294  bytes  each 
Apple  -  336  bytes  each 

None 
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Saued?: 
Descriptions 


Ho 

For  each  of  the  soft  sprites  tl  -  17,  there  is  a  buffer  in  the 
back  Raci  for  sauinq  the  screen  behind  the  sprites.  The 
nouse  (sprite  10)  is  handled  seperately.  Locations  for  the 
buffers  are* 


Comodore: 

ssprlback* 
ssprZback> 
sspr3back> 
sspr4backs 
sspr5back: 
sspr6back: 
S5pr7back: 


Apple: 


ssprlbackx 
sspr2back: 
S5pr3back: 
sspr4back: 
ssprSback: 
S5pr6back: 
sspr7backs 


5133b 
1461 
1587 
16ad 
17d3 

hif? 

half 


S56d0 
15820 
S5970 
§5ac0 
^5cl0 
I5d60 
bebO 


Each  buffer  is  7  butes  wide  by  42  scanlines  high  (292  bytes)  on 
the  Contfflodore  and  8  bytes  vide  by  42  scanlines  high  for  Apple 
soft  sprites.  The  extra  byte  is  needed  because  of  the  App 
7  bit  screen  bytes.   These  buffers  are  large  enough  to  hol_ 
largest  possible  sprite  size  (doubled  in  both  x  and  y)  and 
include  an  extra  byte  in  width  to  save  stuff  on  byte  boundar 


es 

d  the 


Haoe: 

string 

Forrerly: 

Address: 

C64:  $24          C128:  $24         Apple:  $0053 

Size: 

Word 

Default: 

None 

Saved?: 

Yes 

Description: 

Used  by  GEOS  as  a  pointer  to  string  destinations  for  routines 
such  as  GetString. 

Note: 

Haoe: 

StringFaultVec 

Foraerly: 

StringFaultVector 

Address: 

C64:  $84ab       C128:  $84db      Apple:  $0210 

Size: 

Uord 

Default: 

$00 

Saved?: 

Yes 

Description: 

Vector  called  when  an  attenpt  is  aade  to  write  a  character 
past  rightflargin. 

Note: 

Haf&e: 

stringX 

Fornerly: 

Address: 

C64:  $84be       C128:  $84be      Apple:  $022E 

Size: 

Uord 

Default: 

None 
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Sailed?! 

Yes 

Descriptions 

The  X  position  for  string  input 

Note: 

Nane: 

stringY 

Fomerly: 

Address: 

C64:  $84c0        C12B:  $84c0       Apple:  $0230 

Size: 

Byte 

Default: 

None 

Saued?: 

Yes 

Description: 

The  Y  position  for  string  input 

Note: 

Natr«: 

sysDBData 

Fortter 1y: 

Address: 

C64:  i851d        C128:  i851d       Aoole:  i0259. 

Size: 

Byte 

Default: 

None 

Saued?: 

NA 

Description: 

Variable  that  is  used  internally  to  indicate  which  icon  caused 
a  return  to  the  application  (froi  a  dialogue  box).  The  actual 
data  is  returned  to  the  user  in  rOL. 

Note: 

Nane: 

sysFIqCopy 

Forier ]y: 

Address: 

C<4:  ic012        C128:  $c012    '  AoDle:  NA 

Size: 

Byte 

Default: 

None 

Saued?: 

No 

Description: 

This  is  a  copy  of  the  sysRAMFlg  that  is  saued  here  when  going 
into  basic  on  Conaodore.   See  sysRAIIFlg  for  lore  infornation. 

Note: 

Nane: 

sysRAHFlg 

F  ori^r lus 

Address: 

C64:  $88c4        C128:  i88c4       Aoole:  NA 

Size: 

Byte 

Default: 

None 

Saued?: 

No 

Description: 

If  RAtI  expansion  in.  Bank  0  is  reserued  for  the  kernaTs  use. 
This  byte  contains  flags  designating  its  usage: 

Bit  7:   if  1,  $0000-$78FF  used  by  lloueData  routine 
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Bit  6i   \f  1,  $8300-$B8FF  holds  disk  driuers  for  drives  A 
throuoh  C 

Bit  5^  if  1. V'OH^DFF  is  loaded  uith  GEOS  raa  area 

i8400-$88FF  by  ToBasic  routine  when  going  to  BASIC. 

Bit  4:   if  1,  i7E00-$82FF  is  loaded  uith  reboot  code  by  a 

setup  AUTO-EXEC  file,  which  is  loaded  by  the  restart 
code  in  GEOS  at  $C000  if  this  flag  is  set,  at  $6000, 
instead  of  loading  GEOS  BOOT.  Also,  the  area 
$B900-$FC3F  is  saued  for  the  kernal  for  fast  re-boot 
without  sustea  disk  (depending  on  setup  file).  This 
area  should  be  updated  uhe^  input  deuices  are  changed 
(inpleaented  in  1/1.3  deskTop). 


Note: 

Coinfliodore  only 

nasic* 

tntNiinRIk^ 

rorBicr  ly  • 

Address: 

riA»  NO               ri7Q2  NO              Onnlo!  drXflR 

104*  iiH            tiiO"  iiH           nppie*  ^rouo 

Size: 

UnrA 

■oro 

Default: 

$llo 

p .....  • 
Saued?: 

no 

uescr ipc ion* 

lOvai  nuiiDcr  or  diucks  in  currenb  voiuibc. 

Note: 

Nai&e: 

bUroor lags 

r  orBier  ly  • 

Address: 

Si7p: 

4  bytes 

npf  Atlit: 

Nnrtp 

llllllC 

« 

oavcQ: ■ 

Nn 

nu 

UCdwi  ipw  lull* 

Thp  turbo  state  flaos  for  driues  8  throuoh  11  on  Coaaodore 

Note: 

nacie* 

iicoHPemrnc 

r  orBier  ly  • 

HOflress- 

rXAs  6flA97          ri7fl:  ^ftA97  finnlp: 

LOH*  90**7r            Ul&O*  90H7r          npplc*  9rOi/ 

3 1  Zc* 

oy  wc 

uefault: 

AAA 

$U0 

Saued?: 

No 

Description: 

Holds  the  nunber  of  records  in  an  open  ULIR  file 

Note: 

Haote: 

udcClrflode 

Forserly: 

Address: 

C64:  NA           C128:  $88be      Apple:  NA 

Size: 

Byte 

Default: 

Hone  ?? 

Saued?: 

No 
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Description:  Holds  the  current  color  sode  for  C128  color  routines. 
)  Note:  '  ;.: 


nafDe- 

version                                              .  » 

tn^MA^  lit! 

roriier  ly' 

ftddress: 

C<4:  $cOOf        C12B:  $cOOf       Apple: '$EoW  ' 

Size: 

Byte 

Default: 

Hone  

Saved?: 

No 

Description: 

Holds  byte  indicating  uhat  version  of  EEOS  is  running. 

Note: 

na/Be« 

uindouTop 

L  #1  ^  Aft  A  ^   1  1 1  9 

r  orioer  ly  • 

Address: 

U^''  $33          C128:  $33         Apple'  $021E 

Size: 

Byte 

Default: 

$00 

Saued?: 

Yes 

Description: 

Top  line  of  uindou  for  text  clipping 

Note: 

naioe* 

year 

rorBer  ly • 

Address: 

Ci4:  $B5U        C128:  $8516      Apple'  $F200 

Size: 

Byte 

Default: 

86 

Saued?: 

No 

Description: 

Holds  the  year  for  the  tine  of  day  clock. 

Note: 

